MessagesPOST

Send contact (vCard) message

Sends a contact card. message.type is contact and message.contacts is a structured array (one or many cards); UnifyPort generates the vCard. Each card requires name; phones[].number, emails[].address, organization, and title are optional. WhatsApp-only for now; an empty contacts array or a card missing name returns 400 invalid_request, and non-WhatsApp providers return 400 unsupported_message_type. 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.

to

objectrequired

Recipient target with id and type.

id

stringrequired

Channel-side recipient identifier.

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

Text content used when message.type is text.

url

string

Public media URL used by media message types.

file_url

string

Alternative media URL supported by file-based provider adapters.

file_key

string

Provider or storage file reference, when supported.

caption

string

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

contacts[]

object[]

One or more structured contact cards used when message.type is contact.

name

string

Contact display name; required for every contact card.

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.

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 seconds and waveform; use top-level reply_to for quoted replies.

seconds

integer

Optional audio duration in seconds for WhatsApp audio messages; must be zero or greater.

waveform

string

Optional waveform data string for WhatsApp audio messages.

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.

mentions[]

object[]

Members referenced by {{@<id>}} placeholders in text or caption.

id

string

Provider-side member identifier referenced by the matching {{@<id>}} placeholder.

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

Response

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