Справочник API

Сообщения

Отправить медиасообщение

Отправляет медиасообщение. Укажите непустой message.url, message.file_url или message.file_key; URL должен быть абсолютным HTTP(S). Для WhatsApp audio и video seconds — неотрицательное целое число секунд. Только для video диапазон составляет от 0 до 4294967295.

POSThttps://api.unifyport.ai/v1/messages

Перед вызовом

Используйте X-Api-Key нужного рабочего пространства на сервере. Перед запуском замените все заполнители.

Завершите авторизацию и проверьте runtime_status. Авторизация и соединение — разные состояния; HTTP-успех не доказывает готовность.

Откуда взять параметры
account_id
Возьмите data.id из создания или запроса аккаунта. Идентификатор относится к рабочему пространству X-Api-Key. Получить аккаунт
to.id · to.type
Для ответа скопируйте data.conversation.id и data.conversation.type из message.received в to.id и to.type. Для нового адресата следуйте правилам идентификаторов канала. Поддержка единого отправления сообщений

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

Заголовки

X-Api-Key
stringобязательно

API-ключ рабочей области. Рабочая область определяется по этому заголовку.

Content-Type
stringобязательно

Используйте application/json при отправке JSON-тела запроса.

Тело запроса

account_id
stringобязательно

Аккаунт провайдера, отправляющий сообщение.

minLength: 1

to
objectобязательно

Получатель: id и type.

id
stringобязательно

Идентификатор получателя на стороне провайдера.

minLength: 1

type
stringобязательно

Тип получателя: user, group или channel.

enum: user, group, channel

message
objectобязательно

Нормализованный payload сообщения. Текст — message.text, медиа — message.url.

type
stringобязательно

Тип сообщения: text, image, video, audio, document, file или contact.

enum: text, image, video, audio, document, file, contact

text
string

Непустой текст, обязательный при message.type=text.

minLength: 1

caption
string

Необязательная подпись для image, video, document или file.

url
string

Непустой абсолютный HTTP(S) URL; медиа требует url, file_url или file_key.

format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?://

file_url
string

Непустой альтернативный абсолютный HTTP(S) URL; медиа требует один источник.

format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?://

file_key
string

Непустая ссылка на файл провайдера или хранилища; медиа требует один источник.

minLength: 1

contacts[]
object[]

Непустой массив карточек, обязательный при message.type=contact.

minItems: 1

name
string

Непустое отображаемое имя, обязательное для каждой карточки.

minLength: 1

phones[]
object[]

Телефонные номера в карточке контакта.

number
string

Номер телефона; обязателен для каждой записи phone.

type
string

Необязательная метка телефона, например CELL или WORK.

emails[]
object[]

Адреса электронной почты в карточке контакта.

address
string

Адрес электронной почты; обязателен для каждой записи email.

format: email

type
string

Необязательная метка электронной почты, например WORK или HOME.

organization
string

Необязательное название организации контакта.

title
string

Необязательная должность контакта.

provider_data
object

Опции провайдера, например parse_mode для Telegram или seconds для WhatsApp audio / video как неотрицательное целое. Только для video допустим диапазон от 0 до 4294967295; waveform остаётся доступным только для audio. Для ответа с цитатой используйте reply_to верхнего уровня.

seconds
integer

Необязательная длительность сообщений WhatsApp audio и video в секундах как неотрицательное целое. Только для video допустим диапазон от 0 до 4294967295.

minimum: 0

waveform
string

Необязательные данные waveform для сообщений WhatsApp типа audio. Непустые значения должны использовать стандартную кодировку Base64 и после декодирования быть разбираемыми JSON-данными waveform; пустая строка считается отсутствием значения, а другие ошибки формата возвращают HTTP 400 provider_invalid_request.

reply_to
object

Цель цитируемого ответа. Скопируйте data.message.reply_token из входящего webhook без изменений в reply_to.reply_token запроса отправки.

reply_token
string

Непрозрачный токен ответа, скопированный без изменений из data.message.reply_token входящего webhook.

minLength: 1

mentions[]
object[]

Список целей @ для группового сообщения. type=member использует соответствующий id участника Provider; type=all означает @всех и действует только при поддержке Provider, иначе возвращается unsupported_message_type.

type
string

Тип цели @. Если опустить, для совместимости со старыми запросами считается member; type=member требует id, а type=all передается без id и применим только к групповым чатам.

enum: member, all

id
string

Идентификатор участника Provider, обязательный при type=member.

minLength: 1

Как понять результат

Сохраните message_id и provider_ref для сопоставления событий и диагностики. accepted не подтверждает доставку. Проверяйте её по событиям квитанций только при поддержке каналом; форматы идентификаторов различаются.

reply_token — Необязательный непрозрачный дескриптор ответа WhatsApp, возвращаемый, когда канал предоставляет идентификатор сообщения, на который можно ответить. Это не id родительского сообщения.

Ответ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "message_id": "msg_example",
    "account_id": "acc_example",
    "status": "accepted",
    "provider_ref": "provider_msg_example",
    "reply_token": "<opaque WhatsApp reply handle>"
  }
}

Тело ответа

message_id
string

Идентификатор сообщения UnifyPort (msg_...) для принятого сообщения.

account_id
string

Аккаунт провайдера, к которому относится этот ответ.

status
string

Статус приёма; accepted означает, что сообщение поставлено в очередь на доставку провайдеру.

provider_ref
string

Ссылка на сообщение на стороне провайдера, как только провайдер её назначит.

reply_token
string

Необязательный непрозрачный дескриптор ответа WhatsApp, возвращаемый, когда канал предоставляет идентификатор сообщения, на который можно ответить. Это не id родительского сообщения.

Ответы

200

200 OK

Запрос выполнен. См. пример тела ответа.

400

Bad Request

Тело запроса, путь или параметры некорректны.

401

Unauthorized

Заголовок X-Api-Key отсутствует или недействителен.

409

Conflict

Запрошенная операция конфликтует с существующим аккаунтом провайдера или ресурсом.

500

Internal Server Error

Сервис столкнулся с неожиданной ошибкой.

501

Not Implemented

Выбранный провайдер не реализует эту операцию.

502

Bad Gateway

Адаптер или вышестоящий провайдер не смог завершить операцию.

При ошибке запроса

Проверьте HTTP и error.code/numeric_code, сохраните request_id. Исправьте параметры, завершите авторизацию или проверьте runtime. До повторной отправки или записи выясните результат предыдущей попытки. Справочник ошибок

invalid_request · 10000 · 400
Проверьте обязательные поля, форматы и условия канала, затем исправьте запрос.
invalid_api_key · 11001 · 401
Проверьте X-Api-Key и активность рабочего пространства.
provider_not_ready · 30009 · 409
Восстановите авторизацию и соединение, выясните предыдущий результат перед повтором.
unsupported_message_type · 36000 · 400
Выберите поддерживаемую операцию или тип. Повтор не меняет возможности канала.
invalid_reply_token · 36006 · 400
Копируйте входящий reply_token без изменений, не создавайте его из ID сообщения. Нужен канал с поддержкой цитат.