Интеграция входящих веб-крючков

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

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

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

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

Ограничения

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

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

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

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

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

В случае с ссылками 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-запроса.

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

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

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

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

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

Ответ вебхука

В случае успеха (запрос был подтвержден и принят для отправки), 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"
}