Отправка сообщений

Для отправки сообщений необходимо вызвать

 POST https://api.wazzup24.com/v3/message

В теле запроса нужно передавать

Параметры запроса

Параметр

Обязательные параметры отмечены «звездочкой»

Тип Описание
channelId* String Id канала (uuidv4), через который нужно отправить сообщение.
chatType* String Тип чата. Доступные значения:

  • whatsapp — для индивидуальных чатов в WhatsApp,
  • whatsgroup — для групповых чатов в WhatsApp,
  • instagram — для чатов в Инсте,
  • telegram — для индивидуальных чатов в Telegram,
  • telegroup — для групповых чатов в Telegram,
  • vk — для чатов Вконтакте,
  • avito — для чатов Авито
chatId String Id чата (аккаунт контакта в мессенджере):

  • для whatsapp — только цифры, без пробелов и специальных символов в формате 79011112233,
  • для instagram — аккаунт без @ вначале,
  • для whatsgroup — приходит в вебхуках входящих сообщений,
  • для telegram — приходит в вебхуках входящих сообщений и в ответ на запрос при отправке исходящего с параметрами phone или username,
  • для avito и vk приходит в вебхуках входящих сообщений
text String Текст сообщения. Обязателен, если не указан contentUri. Одновременно передавать и text, и contentUri нельзя.

Ограничения:

  • для WhatsApp — до 10 000 символов,
  • для Instagram — до 1000 символов,
  • для WABA и Telegram — 4096 символов,
  • для Вконтакте и Авито — 1000 символов.
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.

Как получить коды шаблонов 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 Нужен для работы с интерактивными сообщениями. Текст кнопки, максимум 25 символов.
buttonsObject.buttons.type   String Тип кнопки. Нужен для работы с интерактивными сообщениями.
Сейчас поддерживаем только текстовый формат — указывайте тип text.
buttonsObject.buttons.id   String Полезная нагрузка с кнопок интерактивного сообщения.
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 с 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. 

В этом запросе отправляем интерактивное сообщение с 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"}
     ]
    }
  },
});

Ответ

Параметр
Тип Описание
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 Неизвестная ошибка. Свяжитесь с нами для получения помощи с идентификатором трассировки ошибки