Для отправки сообщений необходимо вызвать
POST https://api.wazzup24.com/v3/message
В теле запроса нужно передавать
- ключ API в заголовке — он нужен для авторизации,
- параметры сообщения.
Параметры запроса
| Параметр
Обязательные параметры отмечены «звездочкой» |
Тип | Описание |
| channelId* | String | Id канала (uuidv4), через который нужно отправить сообщение. |
| chatType* | String | Тип чата. Доступные значения:
|
| chatId | String | Id чата (аккаунт контакта в мессенджере):
|
| text | String | Текст сообщения. Обязателен, если не указан contentUri. Одновременно передавать и text, и contentUri нельзя.
Ограничения:
|
| contentUri | String | Ссылка на файл для отправки. Параметр обязателен, если не указан text.
Контент должен скачиваться по ссылке без редиректов. Попытка скачать контент будет сразу же после получения запроса, то есть можно делать короткоживущие ссылки. По типу и размеру контента есть ограничения для каждого мессенджера. Одновременно передавать и text, и contentUri нельзя. |
| refMessageId | String | Id сообщения для цитирования |
| crmUserId | String | Id пользователя СRМ, указанный с помощью CRUD users.
Если указано, и если такой пользователь уже существует, покажем в iframe, кто из сотрудников отправил сообщение. Не работает при подключении по Sidecar API. |
| crmMessageId | String | Id сообщения на стороне CRM. Нужен для придания роуту идемпотентности. |
| username | String | Только для Telegram.
Имя пользователя в Telegram, без @ в начале. Можно использовать при отправке сообщений через Telegram, если не известен chatId. |
| phone | String | Только для Telegram.
Телефон контакта в международном формате, без + и иных символов: только цифры с корректным кодом страны. Может использоваться при отправке сообщений через Telegram, если не известен chatId. |
| clearUnanswered | Boolean | Сбросить ли счетчик неотвеченных.
Чтобы сообщение не сбрасывало счетчик, укажите false. Например, при автоматизации. Тогда пользователь CRM увидит уведомление о новом входящем, даже если его клиенту ушел автоматический ответ. Если ничего не указать — исходящее сообщение сбросит счетчик. |
| templateId | String | Код шаблона WABA. |
| templateValues | String
(Array) |
Значения, которыми надо заполнить переменные в шаблоне WABA. |
| buttonsObject | Object | Кнопки, прикрепленные к сообщению. Можно использовать для работы с шаблонами WABA и с интерактивными сообщениями WABA.
Интерактивное сообщение — сообщение с кнопками, которое можно отправлять в активную 24-часовую переписку с клиентом с канала WABA. Шаблоны WABA — шаблоны, которые проходят модерацию в Meta. Их используют, чтобы начать 24-часовую переписку. При работе с шаблонами WABA buttonsObject пригодится, только если хотите привязать к кнопкам полезную нагрузку. Тексты кнопок, которые отправятся с шаблоном WABA, прописывать не надо. |
| buttonsObject.buttons | Object[ ] | Массив объектов с кнопками. Не более 10.
Если кнопок больше 10, возьмем первые 10. |
| buttonsObject.buttons.text | String | Нужен для работы с интерактивными сообщениями. Текст кнопки, максимум 20 символов. |
| buttonsObject.buttons.type | String | Тип кнопки. Нужен для работы с интерактивными сообщениями. Сейчас поддерживаем только текстовый формат — указывайте тип text. |
| buttonsObject.buttons.payload | String | Полезная нагрузка кнопок в шаблонах и интерактивных сообщениях |
Для защиты от возможного дублирования сообщений можно добавлять уникальное для сообщения свойство crmMessageId. Если оно было отправлено, то при поступлении другого запроса с этим же crmMessageId, сообщение не отправится, вернется ошибка 400 Bad Request, { error: ‘repeatedCrmMessageId’, description: ‘You have already sent message with same crmMessageId’ }. Проверка на crmMessageId длится 60 секунд. Если юзер отправит дубль сообщения через 61 секунду и большее, оно уйдет.
Примеры запросов
Обычное сообщение
fetch("https://api.wazzup24.com/v3/message", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer {apiKey|sidecarApiKey}", }, body: { channelId: "e0629e11-0f67-4567-92a9-2237e91ec1b9", refMessageId: "61e5a375-1760-452f-ad73-5318844ffc4f", crmUserId: "string-user-id", crmMessageId: "string-crm-message-id", chatId: "string-chat-id", chatType: "whatsapp", text: "message text" }, });
Шаблон WABA
Запрос на отправку шаблона WABA с 3 кнопками. У каждой есть полезная нагрузка.
fetch("https://api.wazzup24.com/v3/message", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer {apiKey|sidecarApiKey}", }, body: { channelId: "24197d5f-06de-421f-8576-9f6e6cb67f28", chatType: "whatsapp", chatId: "79994621848", templateId: "6201005a-9a6f-486f-bdd5-e6cb86c76ddb", templateValues: ["value"] buttonsObject: { buttons: [ { payload: "button_payload 1" }, { payload: "button_payload 2" }, { payload: "button_payload 3" } ] } }, });
В запросе для шаблонов WABA с кнопками не нужно прописывать текст кнопок. Они проходят модерацию вместе с основным текстом шаблона, поэтому кнопки нельзя менять.
buttonsObject пригодится, только если для кнопок нужно указать полезную нагрузку в поле payload.
Интерактивное сообщение WABA
В этом запросе отправляем интерактивное сообщение с 3 кнопками: «Да», «Нет» и «возможно». У кнопок нет полезной нагрузки.
fetch("https://api.wazzup24.com/v3/message", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer {apiKey|sidecarApiKey}", }, body: { channelId: "e0629e11-0f67-4567-92a9-2237e91ec1b9", refMessageId: "61e5a375-1760-452f-ad73-5318844ffc4f", crmUserId: "string-user-id", crmMessageId: "string-crm-message-id", chatId: "string-chat-id", chatType: "whatsapp", text: "message text", buttonsObject: { buttons: [ {text: "Да", type: "text"}, {text: "Нет", type: "text"}, {text: "возможно", type: "text"} ] } }, });
Ответ
Если отправляете через API шаблон без полезной нагрузки, в вебхуке об ответном сообщении отправим текст соответствующей кнопки. Если отправляете интерактивное сообщение без полезной нагрузки — отправим порядковый номер кнопки, начиная с 0.
| Параметр |
Тип | Описание |
| messageId | String | Идентификатор сообщения.
Указывается только при code=OK |
| chatId | String | Идентификатор чата.
Указывается только при code=OK |
Пример ответа
HTTP/1.1 201 OK
{
"messageId": "f66c53a6-957a-46b2-b41b-5a2ef4844bcb",
"chatId": "79999999999"
}
Ошибки при отправке сообщений
| Код ошибки | Описание |
| BILLING_NOT_ENOUGH_MONEY | Сообщение не отправлено: не хватает денег на балансе WABA |
| CHANNEL_WABA_INVALID_VARS_QUANTITY | Количество переменных не соответствует требуемому |
| MESSAGE_WRONG_CONTENT_TYPE | Неверный тип контента. Возникает, если не удалось определить тип контента или он не поддерживается |
| MESSAGE_ONLY_TEXT_OR_CONTENT | В сообщении может быть текст или вложение. Отправлять одновременно текст и вложение нельзя |
| MESSAGE_NOTHING_TO_SEND | Текст сообщения не найден |
| MESSAGE_TEXT_TOO_LONG | Текст сообщения WhatsApp превышает 10 000 символов |
| MESSAGES_TOO_LONG_INSTAGRAM | Текст сообщения Instagram превышает 10 000 символов |
| MESSAGES_TOO_LONG_TELEGRAM | Текст сообщения Telegram превышает 4096 символов |
| MESSAGES_TOO_LONG_WABA | Текст сообщения WABA слишком длинный. Максимум 1024 для заголовка и 4096 символов для основного текста |
| MESSAGES_TOO_LONG_VK | Текст сообщения Вконтакте превышает 4096 символов |
| MESSAGES_TOO_LONG_AVITO | Текст слишком длинный. Максимум 1000 для подписи и 1000 для текстового сообщения |
| MESSAGES_UNSUPPORTED_CONTENT_TYPE_INSTAPI | Поддерживаемые типы контента для Instagram: jpg, gif, png, ico, bmp |
| MESSAGE_CONTENT_CAN_NOT_BE_BLANK | Файл с контентом не может быть пустым.
Возникает при отправке нетекстового сообщения, к которому не приложили медиа. |
| MESSAGE_CONTENT_SIZE_EXCEEDED | Контент превышает допустимый размер 10 MB |
| MESSAGE_TEXT_CAN_NOT_BE_BLANK | Текстовое сообщение не может быть пустым |
| CHANNEL_NOT_FOUND | Канал, через который отправляется сообщение, не найден в интеграции |
| CHANNEL_BLOCKED | Канал, через который отправляется сообщение, выключен |
| MESSAGE_DOWNLOAD_CONTENT_ERROR | Не удалось скачать контент по указанной ссылке |
| MESSAGES_NOT_TEXT_FIRST | На тарифе «Start» нельзя написать первым |
| MESSAGES_IS_SPAM | WhatsApp оценил это сообщение, как спам |
| CHAT_WRONG_CHAT_TYPE | Неверный тип чата.
Возникает в случае, если вы отправляете исходящее сообщение в мессенджер, не входящий в список [INSTAGRAM, WHATSAPP, VK, TELEGRAM] |
| CHAT_MISSING_CHAT_TYPE | chatType не передан.
Выберите тип чата из списка [INSTAGRAM, WHATSAPP, VK, TELEGRAM] |
| CHAT_INCORRECT_CHAT_ID_WHATSAPP | Некорректный номер WhatsApp.
Номер телефона должен быть в международном формате: содержать от 9 до 16 цифр, для российских номеров начинаться с 7. Без + в начале номера |
| CHAT_INCORRECT_CHAT_ID | Недопустимый формат идентификатора чата: это должно быть целое число или строка длиной от 1 до 200 символов |
| CHAT_INCORRECT_CHAT_ID_WHATSAPPGROUP | Неверный формат идентификатора чата группы WhatsApp. ID должен состоять из трех частей: номера телефона (9–16 цифр), дефиса и идентификатора (10 цифр) |
| CHAT_MISSING_CHAT_ID | chatId не передан |
| VALIDATION_ERROR | Валидационная ошибка параметра, переданного в запрос |
| ACCOUNT_NOT_FOUND | Аккаунт не найден в интеграции |
| CONTACT_NOT_FOUND | Контакт не найден среди контактов аккаунта — чат с таким номером телефона отсутствует |
| CHANNEL_NO_MONEY | Канал не оплачен: не в подписке и не на тестовом периоде |
| MESSAGE_CHANNEL_UNAVAILABLE | Канал, с которого отправляется сообщение, недоступен.
У канала статус «Телефон недоступен» или «Подождите минутку» |
| CONTACT_DETAIL_NOT_FOUND | Нет информации о контакте |
| MESSAGES_ABNORMAL_SEND | Тип чата не соответствует источнику контакта.
Например, такая ошибка может возникнуть, если вы пытаетесь отправить сообщение с канала WhatsApp на канал Instagram |
| MESSAGES_INVALID_CONTACT_TYPE | Тип чата не соответствует источнику контакта Instagram.
Например, такая ошибка может возникнуть, если вы пытаетесь отправить сообщение с канала Instagram на канал WhatsApp |
| MESSAGES_CAN_NOT_ADD | Сообщение не отправлено. Непредвиденная серверная ошибка |
| REFERENCE_MESSAGE_NOT_FOUND | Ошибка возникает при цитировании, если не удалось найти сообщение, к которому прикрепляется цитата.
Проверьте, что в качестве refId передан идентификатор сообщения, полученный от Wazzup |
| UNKNOWN_ERROR | Неизвестная ошибка. |
| UNKNOWN_ERROR_WITH_TRACE_ID | Неизвестная ошибка. Свяжитесь с нами для получения помощи с идентификатором трассировки ошибки |
