MessagesPOST

Send text message

Sends a normalized text message through the selected provider account. message.text must be non-empty; provider_data carries provider-specific fields such as parse_mode, and quoted replies use the top-level reply_to field. Optional opaque WhatsApp reply handle returned after a successful send when the channel provides a referable message identifier. Pass it back unchanged; it is not a parent message id.

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

Headers

X-Api-Key

stringrequired

Workspace API key. The workspace is resolved from this header.

Content-Type

stringrequired

Use application/json when sending a JSON request body.

Path parameters

This endpoint has no path parameters.

Request body

account_id

stringrequired

Provider account that sends the message.

minLength: 1

to

objectrequired

Recipient target with id and type.

id

stringrequired

Channel-side recipient identifier.

minLength: 1

type

stringrequired

Recipient type: user, group, or channel.

enum: user, group, channel

message

objectrequired

Normalized message payload. Text uses message.text; media uses message.url.

type

stringrequired

Message type: text, image, video, audio, document, file, or contact.

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

text

string

Non-empty text content required when message.type is text.

minLength: 1

caption

string

Optional caption for image, video, document, or file messages.

url

string

Non-empty absolute HTTP(S) media URL. Media messages require url, file_url, or file_key.

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

file_url

string

Non-empty alternative absolute HTTP(S) media URL. Media messages require url, file_url, or file_key.

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

file_key

string

Non-empty provider or storage file reference. Media messages require url, file_url, or file_key.

minLength: 1

contacts[]

object[]

Non-empty array of structured contact cards required when message.type is contact.

minItems: 1

name

string

Non-empty contact display name required for every contact card.

minLength: 1

phones[]

object[]

Phone entries included in the contact card.

number

string

Phone number; required for every phone entry.

type

string

Optional phone label such as CELL or WORK.

emails[]

object[]

Email entries included in the contact card.

address

string

Email address; required for every email entry.

format: email

type

string

Optional email label such as WORK or HOME.

organization

string

Optional organization associated with the contact.

title

string

Optional job title associated with the contact.

provider_data

object

Provider-specific options such as Telegram parse_mode or WhatsApp audio / video seconds, which use a non-negative integer. For video only, the allowed range is 0 to 4294967295; waveform remains audio-only. Use top-level reply_to for quoted replies.

seconds

integer

Optional non-negative integer duration in seconds for WhatsApp audio and video messages. For video only, the allowed range is 0 to 4294967295.

minimum: 0

waveform

string

Optional waveform data for WhatsApp audio messages. Non-empty values must use standard Base64 encoding and decode to parseable JSON waveform data; an empty string is treated as omitted, and invalid formats return HTTP 400 provider_invalid_request.

reply_to

object

Quoted-reply target. Copy data.message.reply_token from the inbound webhook into reply_to.reply_token unchanged when supported.

reply_token

string

Opaque reply token copied unchanged from data.message.reply_token in the inbound webhook.

minLength: 1

mentions[]

object[]

Group-message @ target list. type=member uses the corresponding Provider member id; type=all mentions everyone only when the Provider supports it, otherwise unsupported_message_type is returned.

type

string

Mention target type. Omit it for member compatibility; type=member requires id, while type=all omits id and only applies to group chats.

enum: member, all

id

string

Provider member identifier required when type=member.

minLength: 1

Response body

message_id

string

UnifyPort message identifier (msg_...) for the accepted message.

account_id

string

Provider account this response refers to.

status

string

Acceptance status; accepted means the message was queued for delivery to the provider.

provider_ref

string

Provider-side message reference, once the provider assigns one.

reply_token

string

Optional opaque WhatsApp reply handle returned after a successful send when the channel provides a referable message identifier. Pass it back unchanged; it is not a parent message id.

Responses

200

200 OK

Request succeeded. See the example response body.

400

Bad Request

The request body, path, or parameters are invalid.

401

Unauthorized

The X-Api-Key header is missing or invalid.

409

Conflict

The requested operation conflicts with an existing provider account or resource.

500

Internal Server Error

The service encountered an unexpected error.

501

Not Implemented

The selected provider does not implement this operation.

502

Bad Gateway

The provider adapter or upstream provider could not complete the operation.

Request

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"
  }
}'

Response

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