← Справочник API
СообщенияPOST

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

Отправляет текстовое сообщение. message.text не может быть пустым; provider_data содержит специфичные поля, а цитируемый ответ использует reply_to верхнего уровня. Необязательный непрозрачный дескриптор ответа WhatsApp, возвращаемый, когда канал предоставляет идентификатор сообщения, на который можно ответить. Это не id родительского сообщения.

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

Заголовки

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
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

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

Запрос

curl -X POST https://api.unifyport.ai/v1/messages \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example",
  "to": {
    "id": "user_example",
    "type": "user"
  },
  "message": {
    "type": "text",
    "text": "Hello from UnifyPort"
  },
  "provider_data": {
    "parse_mode": "markdown"
  }
}'

Ответ

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