Входящая интеграция с Webhook

Создано на

TimelinesAI позволяет автоматизировать отправку сообщений WhatsApp в ответ на события или действия в уже используемых вами инструментах: CRM, системы поддержки, рекрутинга и т.д.

Событие "Отправить сообщение"

Можно дать команду TimelinesAI на отправку сообщения (с вложением файла или без него) определенному контакту (можно группе). Если в рабочей области подключено несколько учетных записей WhatsApp, можно также указать конкретную учетную запись WhatsApp, которая будет использоваться для отправки сообщения.

Для настройки интеграции владелец рабочей области должен перейти на экран "Integrations / Inbound Webhooks" и сгенерировать новый URL. На этот URL внешняя система должна отправить сообщение в определенном формате (см. подробнее ниже).

Ограничения

  • Максимальный размер вложения - 2 МБ.
  • Непосредственная проверка формата телефонного номера получателя или его подключения к WhatsApp не производится. Перейдите в пользовательский интерфейс Timelines, чтобы проверить статус отправки/прочтения сообщений.

Отправка файлов с помощью входящих Webhooks

Отправка файла: прямая загрузка и услуги хостинга файлов

Необходимо отправлять файлы, используя прямые ссылки на скачивание. Это позволяет получателю действительно получить файл.

При этом следует использовать службу хостинга файлов, которая может предоставить прямую ссылку на скачивание. Такую ссылку лучше всего проверять через инкогнито/приватный просмотр, вставив ссылку в строку поиска. Если загрузка файла начинается сразу же, то ссылка приемлема. Если вместо этого отображается какая-либо веб-страница, то ссылка не может быть использована для отправки файлов.

В случае ссылок на File Hosting Service файлы не могут быть загружены. Вместо этого загружается и отправляется веб-страница общего доступа, что может привести к появлению "поврежденного" файла.

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

Вы также можете запустить этот тест, отправив сообщение webhook на один из своих тестовых номеров. Вы сможете определить, как поведет себя файл, основываясь на том, что мы рассмотрели здесь; если после щелчка на вложении вы получите сообщение об ошибке типа "Файл поврежден", "Несовместимый файл" или "Не удалось загрузить документ X", то это ссылка на сервис хостинга файлов, и ее следует заменить на ссылку прямой загрузки.

Использование кредитного ресурса

  • При отправке сообщения расходуется 1 кредит из квоты на отправку сообщений.
  • При отправке сообщения с непустым текстом и вложением расходуется 2 кредита из квоты на отправку сообщений.
  • Если сообщение не может быть отправлено (недействительный или не подключенный к WhatsApp номер, ошибка сервера WhatsApp), квота на отправку сообщений будет восстановлена (обычно в течение нескольких часов).

Скорость передачи сообщений

  • Сообщения будут отправляться со случайной задержкой около 2 секунд между каждыми двумя сообщениями (чтобы избежать действия механизмов обнаружения спама в WhatsApp).
  • Если активировать webhooks с частотой менее 2 секунд, то сообщения будут ставиться в очередь и рассылаться с задержкой. На каждое поставленное в очередь сообщение будет расходоваться кредит отправки сообщений, поэтому количество поставленных в очередь сообщений не может превышать доступную квоту.

Конфигурация и действия Webhook

  • "Webhook enabled" - позволяет отключить webhook, не удаляя его полностью
  • "Сгенерировать новый URL" - создаст новый уникальный URL, который будет принимать уведомления. Предыдущий URL больше не будет доступен.
  • "Последние попытки отправки" - статус последних попыток активации webhook
  • "Журнал загрузки" - подробный журнал 100 последних попыток активации, полезный для устранения проблем с форматированием.

Формат запроса Webhook

Webhook принимает данные в формате JSON посредством POST-запроса.

  • "action" (обязательное) - в настоящее время поддерживается только одно возможное значение "send"
  • "text" (обязательно)- обычное текстовое сообщение в кодировке UTF-8 для отправки (разметка не поддерживается, кроме разделителя строк "\n"), может быть оставлено пустым, если указан файл.
  • "file_url" (необязательно) - общедоступный URL-адрес файла, который будет загружен и отправлен в качестве вложения.
  • "имя_файла" (необязательно) - имя вложения (должно быть указано, если указан URL).

Получатель может быть указан с помощью одного из следующих параметров:

  • "chat_id" - идентификатор чата, отображаемый в TimelinesAI (может быть найден в URL страницы чата или в полезной нагрузке исходящего webhook). Это позволяет отправлять сообщения группе.
  • "jid" - JID WhatsApp, определяющий контакт или группу
  • "phone" - номер телефона, оформленный в соответствии с международным стандартом телефонных номеров, т.е.:
    [+][код страны][код города][номер местного телефона] (например: +14151231234)
  • "chat_name" - точное название чата в том виде, в котором оно отображается в TimelinesAI

Если в рабочей области подключено несколько учетных записей WhatsApp, используйте следующий дополнительный параметр для указания используемой учетной записи WhatsApp:

  • "whatsapp account phone" (необязательно) - указывает (в виде номера телефона, в международном формате) аккаунт WhatsApp, который будет использоваться для отправки. Если этот параметр не указан, то для отправки будет использоваться последний подключенный активный аккаунт WhatsApp в рабочей области. Примечание: если указан параметр "chat_id", то "whatsapp account phone" не будет учитываться, поскольку каждый чат уже подключен к определенному аккаунту WhatsApp.

Ответ Webhook

В случае успеха (запрос был подтвержден и принят к отправке) Webhook ответит HTTP-статусом 200 и JSON, содержащим message_id созданного сообщения:

{
    "status": "success",
    "data": {
        "message_id": "wa_backend:3EB09FCC85FE99662E46"
    }
}

 

В случае ошибки Webhook ответит HTTP-статусом 40X и JSON с подробной информацией об ошибке, например:

{
"status": 40X,
"data": {},
"message": "Webhook not found"
}

Примеры

Пример 1 - отправка сообщения через конкретный WA-аккаунт на конкретный номер телефона:

{
"action": "send",
"whatsapp account phone" : "+15105566777", 
"phone": "+14151231234", 
"text": "lorem ipsum"
}

Пример 2 - отправка сообщения с текстом и вложением в чат (или группу), указанный по id:

{
"action": "send", 
"chat_id": "77234", 
"text": "lorem ipsum"
"file_url" : "https://timelines.ai/logo.png",
"file_name" : "logo.png"
}
admin
Последние сообщения admin (см. все)
Оглавление