API de Contatos

A API de Contatos permite gerenciar a agenda de contatos do número de WhatsApp ativo: listar, buscar, obter, criar, atualizar o apelido, bloquear/desbloquear e exportar contatos. Com a introdução do BSUID (Business-Scoped User ID) pela Meta, cada contato passa a poder ter — além do telefone (wa_id) — os campos user_id (BSUID), parent_user_id (parent BSUID) e username. Isso permite que um contato exista mesmo sem telefone (por exemplo, quando o usuário adotou um username). Entenda o conceito em BSUID e identificadores de usuário.

Os campos BSUID (user_id, parent_user_id, username) são retornados em todos os endpoints de contato e aparecem preenchidos quando disponíveis ou como null quando ausentes. O campo wa_id (telefone) continua sendo retornado normalmente para compatibilidade retroativa.

Autenticação e base URL

Todos os endpoints desta página usam a base URL de produção e autenticação por Bearer Token: https://api.positus.global/v2

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Os endpoints de listagem, obtenção, criação, apelido, bloqueio e desbloqueio operam sobre o número de WhatsApp ativo da sessão (o número atualmente selecionado pelo usuário autenticado). Eles não recebem o código do número (chave) no path. Apenas o endpoint de exportação recebe o UUID do número no path.

Listar contatos

GET https://api.positus.global/v2/messenger/contacts Lista os contatos do número ativo, paginados (40 por página), ordenados pela data da última mensagem. Suporta busca textual e filtros.

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token

Query Parameters

Name	Type	Description
`query`	string	Busca textual. Casa (via `LIKE`) com `name`, `nickname`, `wa_id` (telefone), `user_id` (BSUID) e `username`. Veja Busca por BSUID.
`blocked`	boolean	Se verdadeiro, retorna apenas contatos bloqueados; caso contrário, apenas os não bloqueados.
`follower_id`	string	UUID de um seguidor, `own` (seguidos por você) ou `without` (sem seguidores).
`tag_id`	string	UUID de uma tag; filtra contatos que possuem a tag.
`messages`	string	`unread` (com mensagens não lidas) ou `read` (todas lidas).

Response

{
  "data": [
    {
      "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
      "name": "Maria Silva",
      "nickname": null,
      "wa_id": "5511999999999",
      "user_id": "BR.1234567890",
      "parent_user_id": "BR.PARENT123456789",
      "username": "maria.silva",
      "messages": [],
      "last_message": null,
      "unread_messages": 0,
      "blocked": false,
      "followers": [],
      "tags": [],
      "window_allowed_until": null,
      "created_at": "2026-07-01T12:00:00.000000Z",
      "updated_at": "2026-07-01T12:00:00.000000Z"
    }
  ],
  "links": { "first": "...", "prev": null, "next": null },
  "meta": { "path": "...", "per_page": 40 }
}

{
  "message": "This action is unauthorized."
}

Retorna 403 quando não há número de WhatsApp ativo associado à sessão.

Obter contato

GET https://api.positus.global/v2/messenger/contacts/{contact} Retorna um contato específico do número ativo, identificado pelo seu UUID (id).

Path Parameters

Name	Type	Description
`contact`	string	UUID do contato (campo `id` da listagem)

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token

Response

{
  "data": {
    "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
    "name": "Maria Silva",
    "nickname": null,
    "wa_id": "5511999999999",
    "user_id": "BR.1234567890",
    "parent_user_id": "BR.PARENT123456789",
    "username": "maria.silva",
    "messages": [],
    "last_message": null,
    "unread_messages": 0,
    "blocked": false,
    "followers": [],
    "tags": [],
    "window_allowed_until": null,
    "created_at": "2026-07-01T12:00:00.000000Z",
    "updated_at": "2026-07-01T12:00:00.000000Z"
  }
}

{
  "message": "No query results for model [Contact]."
}

Criar / atualizar contato

POST https://api.positus.global/v2/messenger/contacts Cria um contato no número ativo. Se já existir um contato com o mesmo identificador de lookup, ele é atualizado em vez de duplicado (comportamento update-or-create). O contato pode ser identificado por telefone (phone) OU por BSUID (user_id) — você precisa informar ao menos um dos dois. Isso permite criar contatos sem telefone, apenas com o BSUID.

Headers

Name	Type	Description
Authorization	string	Autenticação usando Bearer Token
Content-Type	string	application/json

Request Body

Name	Type	Description
`name`	string	Obrigatório. Nome do contato.
`nickname`	string	Opcional. Apelido do contato.
`phone`	string	Obrigatório se `user_id` for omitido. Telefone do contato.
`user_id`	string	Obrigatório se `phone` for omitido. BSUID do contato (ex.: `BR.1234567890`). Veja BSUID.

Chave de lookup (evita duplicidade):

Se user_id for informado, o contato é procurado/atualizado por user_id (prioridade BSUID). Se phone também vier, o telefone é gravado em wa_id.
Se apenas phone for informado, o contato é procurado/atualizado por wa_id.

O username não é usado como chave de identificação — ele é preenchido pelos webhooks da Meta.

Números on-premises: ao criar um contato apenas por phone (sem user_id), a API valida o número junto à WhatsApp API antes de gravar — se o número não existir, retorna 404. Ao criar apenas por user_id (sem telefone), essa validação é ignorada. Em números Cloud API não há validação prévia.

Request Body (contato tradicional — por telefone)

{
  "name": "Maria Silva",
  "nickname": "Maria",
  "phone": "+5511999999999"
}

Request Body (contato por BSUID — sem telefone)

{
  "name": "Maria Silva",
  "user_id": "BR.1234567890"
}

Request Body (BSUID + telefone)

{
  "name": "Maria Silva",
  "user_id": "BR.1234567890",
  "phone": "+5511999999999"
}

Response

{
  "data": {
    "contact": {
      "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
      "name": "Maria Silva",
      "nickname": "Maria",
      "wa_id": "5511999999999",
      "user_id": "BR.1234567890",
      "parent_user_id": null,
      "username": null,
      "messages": [],
      "last_message": null,
      "unread_messages": 0,
      "blocked": false,
      "followers": [],
      "tags": [],
      "window_allowed_until": null,
      "created_at": "2026-07-01T12:00:00.000000Z",
      "updated_at": "2026-07-01T12:00:00.000000Z"
    },
    "recently_created": true
  }
}

{
  "errors": {
    "phone": [
      "Este número de WhatsApp não existe"
    ]
  }
}

{
  "message": "The phone field is required when user id is not present. (and 1 more error)",
  "errors": {
    "phone": [
      "The phone field is required when user id is not present."
    ],
    "user_id": [
      "The user id field is required when phone is not present."
    ]
  }
}

O campo recently_created indica se o contato foi criado agora (true) ou se um contato existente foi atualizado (false).

Atualizar apelido

PUT https://api.positus.global/v2/messenger/contacts/{contact}/nickname Atualiza o apelido (nickname) de um contato existente, identificado pelo UUID.

Path Parameters

Name	Type	Description
`contact`	string	UUID do contato

Request Body

Name	Type	Description
`nickname`	string	Novo apelido do contato.

{
  "nickname": "Cliente VIP"
}

Response

{
  "data": {
    "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
    "name": "Maria Silva",
    "nickname": "Cliente VIP",
    "wa_id": "5511999999999",
    "user_id": "BR.1234567890",
    "parent_user_id": null,
    "username": null,
    "blocked": false
  }
}

Bloquear contato

POST https://api.positus.global/v2/messenger/contacts/{contact}/block Bloqueia um contato existente.

Path Parameters

Name	Type	Description
`contact`	string	UUID do contato

Request Body

Name	Type	Description
`reason`	string	Motivo do bloqueio.

{
  "reason": "Spam"
}

Response

{
  "data": {
    "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
    "name": "Maria Silva",
    "wa_id": "5511999999999",
    "user_id": "BR.1234567890",
    "parent_user_id": null,
    "username": null,
    "blocked": true,
    "block_reason": "Spam"
  }
}

Desbloquear contato

POST https://api.positus.global/v2/messenger/contacts/{contact}/unblock Desbloqueia um contato bloqueado.

Path Parameters

Name	Type	Description
`contact`	string	UUID do contato

Response

{
  "data": {
    "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
    "name": "Maria Silva",
    "wa_id": "5511999999999",
    "user_id": "BR.1234567890",
    "parent_user_id": null,
    "username": null,
    "blocked": false
  }
}

Exportar contatos

POST https://api.positus.global/v2/whatsapp/numbers/{number}/exports/contacts Exporta todos os contatos de um número (identificado pelo UUID no path) em CSV ou XLSX. O arquivo inclui colunas dedicadas para os campos BSUID (user_id, parent_user_id, username).

Path Parameters

Name	Type	Description
`number`	string	UUID do número de WhatsApp

Request Body

Name	Type	Description
`extension`	string	Obrigatório. Formato do arquivo: `csv` ou `xlsx`.

{
  "extension": "xlsx"
}

Response

Retorna o arquivo binário para download (CSV ou XLSX) com as colunas: id, name, nickname, wa_id, user_id, parent_user_id, username, blocked, block_reason, blocked_at, created_at, updated_at.

{
  "message": "The selected extension is invalid.",
  "errors": {
    "extension": [
      "The selected extension is invalid."
    ]
  }
}

Objeto contato

Campos retornados no objeto contato (endpoints de listagem, obtenção e criação):

Campo	Tipo	Descrição
`id`	string	UUID do contato (usado como identificador nas demais rotas).
`name`	string	Nome do contato.
`nickname`	string\|null	Apelido do contato.
`wa_id`	string\|null	Telefone do contato (WhatsApp ID). Pode ser `null` em contatos BSUID-only.
`user_id`	string\|null	BSUID (Business-Scoped User ID) do contato. Veja BSUID.
`parent_user_id`	string\|null	Parent BSUID do contato.
`username`	string\|null	Username público do contato (definido pelo usuário no WhatsApp).
`messages`	array	Reservado (retornado vazio nesta rota).
`last_message`	object\|null	Última mensagem do contato.
`unread_messages`	integer\|null	Quantidade de mensagens não lidas.
`blocked`	boolean	Indica se o contato está bloqueado.
`block_reason`	string	Motivo do bloqueio (presente apenas quando `blocked` é `true`).
`followers`	array	Usuários que seguem o contato.
`tags`	array	Tags associadas ao contato.
`window_allowed_until`	string\|null	Data/hora até a qual a janela de atendimento de 24h está aberta.
`created_at`	string	Data de criação.
`updated_at`	string	Data de atualização.
`blocked_at`	string	Data do bloqueio (presente apenas quando `blocked` é `true`).

Busca por `user_id` ou `username`

O parâmetro query da listagem de contatos faz busca textual (via LIKE, correspondência parcial) sobre os seguintes campos:

name
nickname
wa_id (telefone)
user_id (BSUID)
username

Isso permite localizar contatos BSUID-only (sem telefone) buscando pelo BSUID ou pelo username.

# Buscar por BSUID
GET https://api.positus.global/v2/messenger/contacts?query=BR.1234567890

# Buscar por username
GET https://api.positus.global/v2/messenger/contacts?query=maria.silva

O username é apenas um critério de busca textual — não é uma chave única. Não use username para identificar unicamente um contato; use o id (UUID) ou o user_id (BSUID).

​API de Contatos

​Autenticação e base URL

​Headers

​Listar contatos

​Headers

​Query Parameters

​Response

​Obter contato

​Path Parameters

​Headers

​Response

​Criar / atualizar contato

​Headers

​Request Body

​Request Body (contato tradicional — por telefone)

​Request Body (contato por BSUID — sem telefone)

​Request Body (BSUID + telefone)

​Response

​Atualizar apelido

​Path Parameters

​Request Body

​Response

​Bloquear contato

​Path Parameters

​Request Body

​Response

​Desbloquear contato

​Path Parameters

​Response

​Exportar contatos

​Path Parameters

​Request Body

​Response

​Objeto contato

​Busca por user_id ou username

API de Contatos

Autenticação e base URL

Headers

Listar contatos

Headers

Query Parameters

Response

Obter contato

Path Parameters

Headers

Response

Criar / atualizar contato

Headers

Request Body

Request Body (contato tradicional — por telefone)

Request Body (contato por BSUID — sem telefone)

Request Body (BSUID + telefone)

Response

Atualizar apelido

Path Parameters

Request Body

Response

Bloquear contato

Path Parameters

Request Body

Response

Desbloquear contato

Path Parameters

Response

Exportar contatos

Path Parameters

Request Body

Response

Objeto contato

Busca por `user_id` ou `username`