Contact operations

Get all contacts for a session#

GET /api/v1/channels/{channel_id}/contacts

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Batch-resolve profile picture URLs for up to 50 contacts#

GET /api/v1/channels/{channel_id}/contacts/profile-pictures

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

List the contacts this account has blocked#

GET /api/v1/channels/{channel_id}/contacts/blocked

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Get a specific contact by ID#

GET /api/v1/channels/{channel_id}/contacts/{contactId}

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Save a contact to the account's addressbook, or edit an existing entry#

PUT /api/v1/channels/{channel_id}/contacts/{contactId}

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

firstNameRequired

string

Maximum 100 characters. See JSON schema for all validation constraints.

lastNameOptional

string

Maximum 100 characters. See JSON schema for all validation constraints.

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "lastName": {
      "type": "string",
      "maxLength": 100
    }
  },
  "required": [
    "firstName"
  ],
  "additionalProperties": false
}

Remove a contact from the account's addressbook#

DELETE /api/v1/channels/{channel_id}/contacts/{contactId}

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Check if a phone number exists on WhatsApp#

GET /api/v1/channels/{channel_id}/contacts/check/{number}

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Look up the LID of a phone number#

GET /api/v1/channels/{channel_id}/contacts/{number}/lid

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Get profile picture URL for a contact#

GET /api/v1/channels/{channel_id}/contacts/{contactId}/profile-picture

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Resolve a contact id (e.g. an @lid) to a phone number — best-effort#

GET /api/v1/channels/{channel_id}/contacts/{contactId}/phone

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Block a contact#

POST /api/v1/channels/{channel_id}/contacts/{contactId}/block

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Unblock a contact#

DELETE /api/v1/channels/{channel_id}/contacts/{contactId}/block

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}