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

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

Отправляет карточку контакта. message.type равен contact, а message.contacts — структурированный массив (одна или несколько карточек); UnifyPort генерирует vCard. Каждая карточка требует name; поля phones[].number, emails[].address, organization и title необязательны. Пока только WhatsApp; пустой массив contacts или карточка без name возвращает 400 invalid_request, а провайдеры, отличные от WhatsApp, возвращают 400 unsupported_message_type. Необязательный непрозрачный дескриптор ответа WhatsApp, возвращаемый, когда канал предоставляет идентификатор сообщения, на который можно ответить. Это не id родительского сообщения.

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

Заголовки

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

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

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

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

Параметры пути

У этого эндпоинта нет параметров пути.

Тело запроса

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

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

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

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

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

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

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.

url
string

Публичный URL медиафайла для медиа-сообщений.

file_url
string

Альтернативный URL медиафайла для файловых адаптеров провайдера.

file_key
string

Ссылка на файл у провайдера или в хранилище, если поддерживается.

caption
string

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

contacts[]
object[]

Одна или несколько структурированных карточек для message.type=contact.

name
string

Отображаемое имя контакта; обязательно для каждой карточки.

phones[]
object[]

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

number
string

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

type
string

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

emails[]
object[]

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

address
string

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

type
string

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

organization
string

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

title
string

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

provider_data
object

Опции провайдера, например parse_mode для Telegram или seconds / waveform для аудио WhatsApp. Для ответа с цитатой используйте reply_to верхнего уровня.

seconds
integer

Необязательная длительность аудио WhatsApp в секундах; значение должно быть неотрицательным.

waveform
string

Необязательная строка данных формы волны для аудиосообщений WhatsApp.

reply_to
object

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

reply_token
string

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

mentions[]
object[]

Участники, на которых ссылаются заполнители {{@<id>}} в text или caption.

id
string

Идентификатор участника у провайдера, соответствующий заполнителю {{@<id>}}.

Тело ответа

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

Ответ

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