Operação

Números e pareamento

O número é a linha por onde se fala, e o canal é propriedade dele. Você usa o numberId para enviar, e o estado de conexão para saber se aquela linha está de pé.

Listar os seus números

GET /v1/numbers

curl -H "x-api-key: $NUNTIS_API_KEY" \
  https://api.nuntis.com.br/v1/numbers

{
  "data": [
    {
      "id": "num_4711",
      "channel": "whatsapp-unofficial",
      "label": "Comercial",
      "phoneE164": "+5511999990000",
      "active": true,
      "sendingEnabled": true,
      "status": "connected",
      "since": "2026-08-13T13:30:00.000Z",
      "sinceUnix": 1786533000,
      "lastCheckedAt": "2026-08-13T13:44:30.000Z",
      "lastCheckedAtUnix": 1786534070
    },
    {
      "id": "num_4712",
      "channel": "telegram",
      "label": "Bot de atendimento",
      "phoneE164": null,
      "active": true,
      "sendingEnabled": false,
      "status": "connected",
      "since": null,
      "sinceUnix": null,
      "lastCheckedAt": null,
      "lastCheckedAtUnix": null
    }
  ]
}

A resposta traz todos os seus números e nunca é truncada em silêncio — não há paginação nesta rota. Se um dia houver, ela entra de forma aditiva, sem mudar o que já existe.

Se você ainda não tem número nenhum, a resposta é 200 com data: [] — nunca 404.

A lista traz também os números desativados, com active: false — é o que permite você ver o que desativou.

Cada item traz ainda sendingEnabled: se aquele número pode enviar agora. É uma pergunta diferente de active e de status, e é a que você precisa antes de enfileirar — veja abaixo.

Pode enviar? sendingEnabled

active e status não respondem à pergunta que importa na hora de enviar. Um número pode estar ativo, conectado — e mesmo assim não enviar. Quem responde isso é sendingEnabled, presente em GET /v1/numbers e em GET /v1/numbers/{id}/status.

O ciclo de vida de um número

cadastrado    active: true   status: disconnected   sendingEnabled: true
pareado       active: true   status: connected      sendingEnabled: true
(desligado)   active: true   status: connected      sendingEnabled: false

O número já nasce podendo enviar — cadastrar e parear não deixam nenhuma liberação pendente. O que falta, entre o cadastro e a primeira mensagem, é o pareamento: sem sessão conectada não há por onde sair.

A terceira linha não é uma etapa do ciclo, e sim um estado que pode aparecer a qualquer momento: a operação do Nuntis desliga o envio de um número para proteger a linha, e há também o desligamento geral do serviço, que zera o envio de todos de uma vez. Não existe ordem garantida aqui — por isso o campo se lê, não se deduz do ponto do fluxo em que você está. Veja Provisionamento para o cadastro.

Estados de conexão

Não há ordem entre os estados

Ao contrário do status de mensagem, aqui não existe escada. Um número vai e volta livremente entre conectado, desconectado e pareamento pendente — um telefone sai do ar e volta, e um “estado que só avança” faria o contrato mentir sobre a realidade física.

Consultar o estado de um número

GET /v1/numbers/{id}/status

{
  "status": "connected",
  "since": "2026-08-13T13:30:00.000Z",
  "sinceUnix": 1786533000,
  "lastCheckedAt": "2026-08-13T13:44:30.000Z",
  "lastCheckedAtUnix": 1786534070,
  "reason": null,
  "sendingEnabled": true
}

O reason é sempre presente e null na esmagadora maioria das transições — queda de canal, encerramento pedido por você e pareamento normal não têm motivo declarado. Quando ele vem preenchido, é porque o telefone que pareou não bate com o que você cadastrou: os dois motivos e o que fazer.

Você não precisa consultar em laço: mudanças de estado chegam sozinhas pelo evento connection.updated, e o numberId de lá é o mesmo dos eventos de mensagem.

Parear um número

POST /v1/numbers/{id}/pairing

curl -X POST -H "x-api-key: $NUNTIS_API_KEY" \
  https://api.nuntis.com.br/v1/numbers/num_4711/pairing

{
  "status": "qr_required",
  "qr": {
    "code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "format": "png-data-uri",
    "obtainedAt": "2026-08-13T13:45:12.000Z",
    "obtainedAtUnix": 1786534112
  },
  "hint": { "refreshAfterSeconds": 20 }
}

O qr.code é um data URI completo, pronto para usar direto:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." alt="Código de pareamento">

Se o número já estiver conectado, a resposta é 200 com status: "connected" e qr: null. Pedir pareamento do que já está pareado não é erro.

Fluxo de pareamento

1. Chame POST /v1/numbers/{id}/pairing.
2. Se vier status: "connected", acabou.
3. Exiba o qr.code ao operador.
4. Repita a chamada a cada ~20 s e substitua a imagem, enquanto ninguém escanear.
5. Pare quando chegar connection.updated com state: "connected", ou quando a chamada devolver connected.

Encerrar a sessão

DELETE /v1/numbers/{id}/session

curl -X DELETE -H "x-api-key: $NUNTIS_API_KEY" \
  https://api.nuntis.com.br/v1/numbers/num_4711/session

Destrói a sessão pareada: o número volta a exigir pareamento. É idempotente — sessão já encerrada devolve o mesmo resultado.

O número continua cadastrado e ativo: o que morre é a sessão.

Sinalizar presença

POST /v1/numbers/{id}/presence

curl -X POST https://api.nuntis.com.br/v1/numbers/num_4711/presence \
  -H "x-api-key: $NUNTIS_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "conversationId": "conv_991", "state": "typing" }'

Estados aceitos: typing, recording, paused e seen. O último marca como lidas as mensagens recebidas daquela conversa. A resposta é 204, sem corpo.

Capacidade do canal

GET /v1/channels

Consulte uma vez, no boot da sua aplicação, e guarde. A declaração diz o que cada canal sabe fazer — e é a resposta certa para quase toda pergunta que começa com “mas neste canal…”. O id daqui é o mesmo valor que aparece em channel na listagem de números: é por ele que você liga um número à sua capacidade.

A resposta é completa — cada canal traz todos os campos, sem omissão. Abaixo ela está transcrita inteira, como está no ar hoje:

{
  "data": [
    {
      "id": "whatsapp-unofficial",
      "texto": true,
      "midia": ["image", "audio", "video", "document"],
      "midiaRecebimento": ["image", "audio", "video", "document", "sticker"],
      "reply": true,
      "botoes": false,
      "audioPtt": true,
      "deliveryReceipts": "read",
      "pairing": "qr",
      "janelaResposta": { "exige": false },
      "template": { "exige": false },
      "presence": true,
      "presenceStates": ["typing", "recording", "paused", "seen"],
      "grupos": false,
      "echoDeSaida": true,
      "idDeMensagemReservavel": true,
      "avatar": true,
      "provisioning": "self-service"
    },
    {
      "id": "telegram",
      "texto": true,
      "midia": ["image", "audio", "video", "document"],
      "midiaRecebimento": ["image", "audio", "video", "document", "sticker"],
      "reply": true,
      "botoes": false,
      "audioPtt": true,
      "deliveryReceipts": "none",
      "pairing": "none",
      "janelaResposta": { "exige": true },
      "template": { "exige": false },
      "presence": true,
      "presenceStates": ["typing", "recording"],
      "grupos": false,
      "echoDeSaida": false,
      "idDeMensagemReservavel": false,
      "avatar": false,
      "provisioning": "managed"
    }
  ]
}

Os valores acima são o retrato de hoje, não uma promessa: eles mudam quando um canal ganha capacidade, e canal novo entra de forma aditiva. Por isso a regra é sempre a mesma — leia o campo, não deduza pelo nome do canal.

O que cada campo decide na sua interface

Canal novo aparece aqui de forma aditiva. Se você lê a declaração em vez de assumir, o seu código já nasce pronto para ele.

Nuntis — serviço de mensageria multicanal da Devari.