API Reference

Contacts

Add contact

Adds a contact to the channel account. Provide at least one of phone_number or username. whatsapp_options is WhatsApp-only; unsupported channels return 501 unsupported_by_provider.

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/contacts/add

Before you call

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

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

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.

Path parameters

account_id
stringrequired

Identifier used in the contacts route.

Request body

phone_number
string

Phone number containing a country or region code, using digits only with no plus sign, spaces, or separators. Provide phone_number or username.

minLength: 1

username
string

Channel username. Provide username or phone_number; format rules depend on the target channel.

minLength: 1

whatsapp_options
object

Optional WhatsApp-only contact settings. Pass first_name, full_name, and sync_to_device_contacts only as fields nested inside whatsapp_options; omit this object for other channels.

first_name
string

Optional WhatsApp contact first name.

full_name
string

Optional WhatsApp contact full name.

sync_to_device_contacts
boolean

Whether to also save the contact to the system address book of the device linked to this WhatsApp account. Defaults to false.

Understand the result

Use the documented response fields and HTTP status. Successful 204 responses have no body; use X-Request-Id for diagnosis. Follow the related operations for the next step.

Response 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "8600000000000@s.whatsapp.net",
    "conversation_id": "123456789012345@lid",
    "display_name": "Alice Example",
    "avatar_url": "",
    "provider_user_id": "8600000000000@s.whatsapp.net",
    "extra": {
      "phone": "8600000000000"
    }
  }
}

Response body

id
string

Contact identifier.

conversation_id
string

Conversation identifier for this contact; use it to send messages or locate the chat.

display_name
string

Contact display name, or an empty string when missing.

avatar_url
string

Contact avatar URL, or an empty string when missing.

provider_user_id
string

Channel-side user identifier for the contact.

is_blocked
boolean

Whether the contact is blocked by the connected account.

extra
object

Provider-specific extra fields, such as phone.

phone
string

WhatsApp phone JID 中解析出的纯手机号。

first_name
string

当前账号通讯录中保存的联系人简称或名字部分。

full_name
string

当前账号通讯录中保存的完整联系人名称。

push_name
string

联系人自行在 WhatsApp 设置的个人名称。

business_name
string

WhatsApp Business 账号的商业或认证名称。

redacted_phone
string

Provider 仅返回部分号码时的遮蔽手机号。

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.