Skip to main content
Получайте уведомления в реальном времени о событиях электронной почты. Веб-хуки — лучший способ получить информацию в реальном времени о том, что происходит с вашими письмами. Вместо того, чтобы постоянно спрашивать API AgentInbox, есть ли новое письмо (процесс, называемый опросом), вы можете зарегистрировать URL, и мы отправим вам запрос POST с деталями, как только произойдет событие. Этот управляемый событиями подход более эффективен и позволяет вам создавать быстрые, отзывчивые агенты, которые могут мгновенно реагировать на входящие сообщения.

​
Зачем использовать веб-хуки?

  • Скорость в реальном времени: создавайте агентов-переговорщиков, которые могут отвечать на входящие письма за секунды.
  • Эффективность: устраняет необходимость в постоянном опросе, что экономит ваши вычислительные ресурсы и упрощает логику вашего приложения.

​
Рабочий процесс веб-хука

Процесс простой:
1

1. Создайте конечную точку веб-хука

Это открытый URL на вашем сервере, который может принимать запросы POST. Для локальной разработки инструмент, подобный ngrok, идеально подходит для создания защищенного открытого URL, который туннелирует на вашу локальную машину. Ваша конечная точка должна немедленно вернуть ответ 200 OK, чтобы подтвердить получение и обработать полезную нагрузку в фоновом режиме, чтобы избежать тайм-аутов.
2

2. Зарегистрируйте конечную точку с помощью AgentInbox

Вы можете зарегистрировать свой URL, используя API AgentInbox. Когда вы создаете веб-хук, вы указываете URL вашей конечной точки, а также типы событий, которые вы хотите получать.client.webhooks.create( url="https://<your-ngrok-url>.ngrok-free.app/webhooks")
3

3. AgentInbox отправляет события

Когда во входящем ящике получается новое сообщение, AgentInbox немедленно отправит запрос POST с JSON полезной нагрузкой на зарегистрированный URL.

​
Структура полезной нагрузки

Когда AgentInbox отправляет веб-хук, полезная нагрузка будет иметь следующую структуру.
Полезная нагрузка веб-хука
{
  "event_type": "message.received",
  "event_id": "evt_123abc...",
  "message": {
    "from_": ["sender@example.com"],
    "organization_id": "org_abc123...",
    "inbox_id": "inbox_def456...",
    "thread_id": "thd_ghi789...",
    "message_id": "msg_jkl012...",
    "labels": ["received"],
    "timestamp": "2023-10-27T10:00:00Z",
    "reply_to": ["reply-to@example.com"],
    "to": ["recipient@example.com"],
    "cc": ["cc-recipient@example.com"],
    "bcc": ["bcc-recipient@example.com"],
    "subject": "Email Subject",
    "preview": "A short preview of the email text...",
    "text": "The full text body of the email.",
    "html": "<html>...</html>",
    "attachments": [
      {
        "attachment_id": "att_pqr678...",
        "filename": "document.pdf",
        "content_type": "application/pdf",
        "size": 123456,
        "inline": false
      }
    ],
    "in_reply_to": "msg_parent456...",
    "references": ["msg_ref1...", "msg_ref2..."],
    "sort_key": "some-sort-key",
    "updated_at": "2023-10-27T10:00:05Z",
    "created_at": "2023-10-27T10:00:00Z"
  }
}

​
Описания полей

  • event_type (string): имя события. В настоящее время это всегда будет message.received.
  • event_id (string): уникальный идентификатор для этой конкретной доставки события.
  • message (object): словарь, содержащий полные детали полученного письма.
    • from_ (array<string>): адрес электронной почты отправителя. Обратите внимание на завершающий символ подчеркивания, чтобы избежать конфликта с ключевым словом Python.
    • organization_id (string): ID вашей организации.
    • inbox_id (string): ID входящего ящика, который получил сообщение.
    • thread_id (string): ID цепи беседы.
    • message_id (string): уникальный ID этого конкретного сообщения.
    • labels (array<string>): метки, связанные с сообщением (например, received, sent).
    • subject (string): строка темы письма.
    • preview (string): короткое простой текст предпросмотр тела письма.
    • text (string): полное простой текст тела письма.
    • html (string): полное HTML тело письма, если оно присутствует.
    • attachments (array<object>): список вложений, каждое с его собственным attachment_id, filename, content_type, size и статусом inline.
    • in_reply_to (string): message_id письма, на которое это сообщение является ответом, если применимо.

​
Дальнейшие шаги

События веб-хуков

Изучите полный список доступных типов событий и их полезные нагрузки данных.

Проверка веб-хуков

Узнайте, как проверить подписи веб-хуков для защиты ваших конечных точек.

Пример: управляемый событиями агент

Создайте полностью развертываемого управляемого событиями агента, который может отвечать на письма в реальном времени.