curl --request POST \
  --url https://{instance}/wapi/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "5534992341048",
  "name": "Maria Souza"
}
'

{
  "requestId": "req_5a10bc",
  "created": false,
  "contact": {
    "id": 601,
    "name": "Maria Souza",
    "number": "5534992341048",
    "email": null,
    "document": null,
    "channel": "whatsapp",
    "profilePicUrl": null,
    "disableBot": false,
    "tags": [],
    "createdAt": "2026-08-10T12:00:00.000Z",
    "updatedAt": "2026-09-23T09:30:00.000Z"
  }
}

{
  "requestId": "req_5a10bd",
  "created": true,
  "contact": {
    "id": 602,
    "name": "João Lima",
    "number": "5534998877665",
    "email": null,
    "document": null,
    "channel": "whatsapp",
    "profilePicUrl": null,
    "disableBot": false,
    "tags": [],
    "createdAt": "2026-09-23T09:31:00.000Z",
    "updatedAt": "2026-09-23T09:31:00.000Z"
  }
}

{
  "error": "ERR_MISSING_NUMBER",
  "code": "ERR_MISSING_NUMBER"
}

{
  "error": "Token não fornecido",
  "code": "ERR_TOKEN_MISSING"
}

{
  "error": "Token sem permissão para esta ação",
  "code": "ERR_SCOPE_MISSING"
}

{
  "error": "ERR_WHATSAPP_NOT_FOUND",
  "code": "ERR_WHATSAPP_NOT_FOUND"
}

{
  "error": "ERR_NUMBER_NOT_ON_WHATSAPP",
  "code": "ERR_NUMBER_NOT_ON_WHATSAPP"
}

{
  "error": "Limite de requisições excedido",
  "code": "ERR_RATE_LIMITED"
}

Contatos

Criar ou atualizar contato por número (upsert)

Cria o contato se o número ainda não existe na sua conta, ou atualiza o que já existe — a chave de identidade é number, não um id. Devolve 201 quando criou e 200 quando atualizou (created no corpo confirma qual foi). Só os campos enviados e não vazios são gravados na atualização; extraInfo (lista { name, value }) substitui integralmente os campos extras existentes do contato quando enviado. Duas chamadas concorrentes para o mesmo número novo são seguras: uma cria, a outra detecta a corrida e vira atualização automaticamente — nenhuma das duas falha nem duplica o contato. Com validateNumber=true, valida o número no WhatsApp antes do upsert (só em conexões não-WABA; conexões WABA não bloqueiam) usando a conexão de whatsappId, ou a padrão da sua conta se omitido; número que não existe no WhatsApp devolve 422 ERR_NUMBER_NOT_ON_WHATSAPP. whatsappId que não é uma conexão da sua conta devolve 404 ERR_WHATSAPP_NOT_FOUND; se omitido e a sua conta não tiver nenhuma conexão whatsapp/waba devolve 404 ERR_NO_CONNECTION_AVAILABLE. number ausente devolve 400 ERR_MISSING_NUMBER. Requer escopo contacts:write.

POST

contacts

curl --request POST \
  --url https://{instance}/wapi/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "5534992341048",
  "name": "Maria Souza"
}
'

{
  "requestId": "req_5a10bc",
  "created": false,
  "contact": {
    "id": 601,
    "name": "Maria Souza",
    "number": "5534992341048",
    "email": null,
    "document": null,
    "channel": "whatsapp",
    "profilePicUrl": null,
    "disableBot": false,
    "tags": [],
    "createdAt": "2026-08-10T12:00:00.000Z",
    "updatedAt": "2026-09-23T09:30:00.000Z"
  }
}

{
  "requestId": "req_5a10bd",
  "created": true,
  "contact": {
    "id": 602,
    "name": "João Lima",
    "number": "5534998877665",
    "email": null,
    "document": null,
    "channel": "whatsapp",
    "profilePicUrl": null,
    "disableBot": false,
    "tags": [],
    "createdAt": "2026-09-23T09:31:00.000Z",
    "updatedAt": "2026-09-23T09:31:00.000Z"
  }
}

{
  "error": "ERR_MISSING_NUMBER",
  "code": "ERR_MISSING_NUMBER"
}

{
  "error": "Token não fornecido",
  "code": "ERR_TOKEN_MISSING"
}

{
  "error": "Token sem permissão para esta ação",
  "code": "ERR_SCOPE_MISSING"
}

{
  "error": "ERR_WHATSAPP_NOT_FOUND",
  "code": "ERR_WHATSAPP_NOT_FOUND"
}

{
  "error": "ERR_NUMBER_NOT_ON_WHATSAPP",
  "code": "ERR_NUMBER_NOT_ON_WHATSAPP"
}

{
  "error": "Limite de requisições excedido",
  "code": "ERR_RATE_LIMITED"
}

Authorizations

Authorization

string

header

required

Token criado em API → Tokens no painel. Prefixo wtx_live_ (ou wtx_test_).

Body

application/json

number

string

required

E.164 sem + (DDI+DDD+número). Chave de identidade do upsert.

Example:

"5534992341048"

name

string | null

document

string | null

disableBot

boolean | null

extraInfo

object[] | null

Substitui integralmente os campos extras do contato, quando enviado.

Show child attributes

validateNumber

boolean | null

Se true, valida o número no WhatsApp antes do upsert (só canais não-WABA; WABA não bloqueia).

whatsappId

integer | null

Conexão usada para validateNumber. Omitido = conexão padrão da sua conta.

Response

Contato já existia — atualizado com os campos preenchidos.

requestId

string

created

boolean

Example:

false

contact

object

Show child attributes

Start

Reference

Criar ou atualizar contato por número (upsert)

Authorizations

Body

Response