Messages

Send contact (vCard) message

Sends a contact card. message.contacts must be a non-empty array and every card requires a non-empty name; phones[].number, emails[].address, organization, and title are optional. WhatsApp-only for now; invalid contact content returns 400 invalid_request, and non-WhatsApp providers return 400 unsupported_message_type.

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

Before you call

Use a server-side X-Api-Key for the workspace that owns the resource. Replace every placeholder before running a sample.

Complete the selected authorization flow and check runtime_status. Authorization and connection state are separate; HTTP success alone does not establish readiness.

Prepare your parameters

account_id: Use data.id from account creation or an account query. Account identifiers belong to the workspace selected by X-Api-Key. Get account
to.id · to.type: For a reply, copy data.conversation.id and data.conversation.type from message.received into to.id and to.type. For a new recipient, follow the channel-specific identifier rules. Unified message sending support

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

Request parameters

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.

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

Understand the result

Save message_id and provider_ref to correlate later events or troubleshoot. accepted is not a delivery receipt. Use receipt events only where the channel supports them; identifier formats vary by channel.

reply_token — 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.

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

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.

If the request fails

Inspect HTTP status and error.code/numeric_code, and keep request_id for diagnosis. Correct invalid parameters, complete required authorization or check runtime state as appropriate. Confirm the outcome before retrying a send or another write. Error reference

invalid_request · 10000 · 400: Check required fields, formats and channel conditions, then correct the request.
invalid_api_key · 11001 · 401: Check X-Api-Key and whether the workspace is active.
provider_not_ready · 30009 · 409: Check authorization and runtime. Restore the connection and confirm the previous result before retrying.
unsupported_message_type · 36000 · 400: Choose a supported operation or message type. Repeating the same request does not add channel support.
invalid_reply_token · 36006 · 400: Copy the inbound reply_token unchanged, not a message ID. Quoted replies require a supporting channel.