Сообщения

Отправить сообщение с контактом (vCard)

Отправляет карточки контактов. message.contacts должен быть непустым массивом, а name каждой карточки — непустой строкой. Пока поддерживает только WhatsApp; неверные данные возвращают 400 invalid_request.

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. Для нового адресата следуйте правилам идентификаторов канала. Поддержка единого отправления сообщений

Запрос

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": "contact",
    "contacts": [
      {
        "name": "Jane Doe",
        "phones": [{ "number": "+8613800000000", "type": "CELL" }],
        "emails": [{ "address": "jane@example.com" }],
        "organization": "ACME",
        "title": "PM"
      }
    ]
  }
}'

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

Заголовки

X-Api-Key

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

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

Content-Type

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

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

Тело запроса

provider_data

object

Опции отправки провайдера, действующие только для поддерживаемых провайдеров и типов сообщений. seconds для WhatsApp audio/video — неотрицательное целое. Только для video допустим диапазон от 0 до 4294967295, waveform — только для audio. Для ответа с цитатой используйте reply_to верхнего уровня, если он поддерживается. Для sticker поле provider_data нужно опустить или передать пустой объект; не объект возвращает 400 invalid_request, непустой объект — 400 provider_invalid_request.

seconds

integer

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

minimum: 0

waveform

string

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

account_id

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

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

minLength: 1

to

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

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

id

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

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

minLength: 1

type

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

Стандартный тип беседы: user, group или channel. Группы объявлений сообщества WhatsApp по-прежнему используют group.

enum: user, group, channel

message

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

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

type

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

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

enum: text, image, video, audio, document, file, contact, link_preview, poll, sticker

text

string

Непустой текст, обязательный для text и link_preview. Для link_preview нужен хотя бы один непробельный символ; WhatsApp также требует включить в текст link_preview.url без изменений.

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

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

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

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

link_preview

object

Обязателен вместе с text только для message.type=link_preview; нельзя смешивать с другими данными сообщения. Общая структура требует только url; необязательные title и description допускают пустую строку, но не null. Политика отправки WhatsApp в этом API требует непустые title/image_url и ограничивает title до 255, а description до 1024 символов Unicode.

url

string

Обязательная целевая ссылка: абсолютный HTTP(S) URI с именем хоста без пробельных символов; в квадратных скобках допустимы только литералы IPv6. Сохраняется без изменений; доступность ресурса не гарантируется.

pattern: ^[Hh][Tt][Tt][Pp][Ss]?://(?:[^/?#@\s]*@)?(?:\[[0-9A-Fa-f:.]+\]|[^/?#:@\s\[\]]+)(?::[0-9]*)?(?:[/?#]|$)

title

string

Необязательный заголовок предпросмотра; пустая строка допустима, null запрещён. WhatsApp требует непустое значение длиной до 255 символов Unicode.

description

string

Необязательное описание предпросмотра; пустая строка допустима, null запрещён. WhatsApp допускает до 1024 символов Unicode.

image_url

string

Необязательный URI изображения; для WhatsApp обязателен и не может быть пустым. Нужен абсолютный HTTP(S) URI с именем хоста без пробельных символов; в квадратных скобках допустимы только литералы IPv6. Сохраняется без изменений; доступность ресурса не гарантируется.

pattern: ^[Hh][Tt][Tt][Pp][Ss]?://(?:[^/?#@\s]*@)?(?:\[[0-9A-Fa-f:.]+\]|[^/?#:@\s\[\]]+)(?::[0-9]*)?(?:[/?#]|$)

poll

object

Обязателен только для message.type=poll; нельзя смешивать с text или другими данными сообщения. Требуются question, options и max_selections. Вопрос и заголовки вариантов сохраняются без изменений. Общая структура не ограничивает длину вопроса, максимальное число вариантов или повторение заголовков; провайдеры могут вводить дополнительные ограничения.

question

string

Обязательный вопрос опроса с хотя бы одним непробельным символом; сохраняется без изменений.

minLength: 1 · pattern: \S

options[]

object[]

Обязательный массив минимум из двух вариантов, каждый с title.

minItems: 2

title

string

Обязательный заголовок варианта с хотя бы одним непробельным символом. Отправляется без trim, изменения регистра или нормализации Unicode.

minLength: 1 · pattern: \S

max_selections

integer

Обязательное максимальное число выбираемых вариантов на одного участника, не число участников. Целое от 1 до количества options, проверяемое API. Числа с целым значением, например 1.0 и 1e0, равны 1; дробные значения недопустимы.

minimum: 1

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 сообщения. Нужен канал с поддержкой цитат.