Enviar e receber

Enviar mensagens

Um único endpoint envia por qualquer canal. Quem determina o canal é o número remetente, não um parâmetro seu.

POST /v1/messages

O corpo

{
  "numberId": "num_4711",
  "to": { "phone": "+5511999990000" },
  "type": "text",
  "text": { "body": "Olá! Vi que você se inscreveu — posso ajudar?" }
}

* to e conversationId são alternativas — mande um dos dois, nunca os dois.

Regras que valem saber antes de codar

• phone é E.164 estrito: + seguido de 7 a 15 dígitos, sem separadores. +5511999990000 vale; (11) 99999-0000 e 5511999990000 não.
• Campo desconhecido é recusado. Escrever bodyText em vez de text devolve 400 em vez de ser descartado em silêncio — você precisa saber agora, e não descobrir pela mensagem vazia que chegou ao seu cliente.
• Confira a capacidade do canal antes de enviar mídia ou usar replyTo. Um canal que não declara a capacidade responde 422 CHANNEL_CAPABILITY_UNSUPPORTED.

Citar uma mensagem

Todo identificador de mensagem que o Nuntis publica vive no mesmo espaço: id, replyTo e quotedMessageId são sempre msg_…. O identificador interno do canal não atravessa a API — ele não serve em nenhuma rota nossa.

Isso fecha o ciclo sem tradução do seu lado: o quotedMessageId que você recebeu numa mensagem pode ser copiado direto para o replyTo do envio, e pode ser usado em GET /v1/messages/{id} para buscar a mensagem citada.

• A citada precisa estar na mesma conversa. Um replyTo de outra thread é ignorado — nunca é aplicado à conversa errada.
• Citação que não resolve não derruba o envio. A mensagem sai sem a citação, com 202 normal: perder o balão de citação é melhor que não entregar a mensagem.
• quotedMessageId é omitido quando a mensagem citada nunca passou pelo Nuntis — é o caso de uma conversa anterior ao pareamento do número. Não há identificador nosso a publicar, e o do canal não é exposto no lugar dele.
• Continuamos aceitando o identificador do canal em replyTo, para não quebrar integrações que já o usavam. Prefira o msg_…: é o formato documentado e o único que também funciona nas rotas de leitura.

Responder dentro de um grupo

Não há rota nem payload próprios: use o mesmo POST /v1/messages, com o conversationId da conversa de grupo que você recebeu. O que chega ao grupo é a mensagem do seu número — em outbound de grupo, from é o seu número, porque quem fala é o operador.

{
  "numberId": "num_5",
  "conversationId": "conv_9931",
  "type": "text",
  "text": { "body": "Fechado, pessoal. Mando o orçamento ainda hoje." }
}

Abrir conversa com quem só tem lid

Em grupo, quem não expõe o telefone chega até você identificado apenas por LID — você recebe from.lid e from.phoneE164 ausente. Para falar com essa pessoa em 1:1, copie o from.lid para to.lid:

{
  "numberId": "num_5",
  "to": { "lid": "999990000000000@lid" },
  "type": "text",
  "text": { "body": "Oi! Falo do time X, vi sua mensagem no grupo Y." }
}

• O contato criado fica sem telefone, e isso é ausência honesta: o Nuntis não deriva telefone a partir de LID em lugar nenhum. Em GET /v1/conversations ele aparece com contact.lid e sem contact.phoneE164.
• to: { "jid": "…@lid" } continua funcionando e produz exatamente a mesma conversa. O campo lid apenas valida a forma (dígitos + @lid) e espelha o from.lid que você recebeu.
• Limite conhecido: se você já tem um contato dessa pessoa por telefone e o número remetente ainda não aprendeu o LID dela, o envio por lid cria uma segunda conversa. Unificar contatos duplicados é trabalho separado, ainda não disponível.

A resposta: 202, não 200

{
  "messageId": "msg_18273",
  "status": "queued",
  "acceptedAt": "2026-08-13T18:12:03.000Z",
  "acceptedAtUnix": 1786126323
}

Exemplo completo

curl -X POST https://api.nuntis.com.br/v1/messages \
  -H "x-api-key: $NUNTIS_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "numberId": "num_4711",
    "to": { "phone": "+5511999990000" },
    "type": "text",
    "text": { "body": "Olá! Posso te ajudar?" }
  }'

const { randomUUID } = require('crypto');

async function enviarTexto({ numberId, telefone, corpo, chaveDeEnvio }) {
  const resposta = await fetch(`${process.env.NUNTIS_URL}/v1/messages`, {
    method: 'POST',
    headers: {
      'x-api-key': process.env.NUNTIS_API_KEY,
      'content-type': 'application/json',
      // Gerada junto com a DECISÃO de enviar, não aqui. Veja abaixo.
      'idempotency-key': chaveDeEnvio ?? randomUUID(),
    },
    body: JSON.stringify({
      numberId,
      to: { phone: telefone },
      type: 'text',
      text: { body: corpo },
    }),
  });

  const corpoResposta = await resposta.json();

  if (!resposta.ok) {
    // { code, message, retryable, source } — decida o retry por `retryable`.
    throw Object.assign(new Error(corpoResposta.message), corpoResposta);
  }

  // 202: aceita e agendada. O estado real chega pelo webhook.
  return corpoResposta.messageId;
}

Idempotência

Mande o header Idempotency-Key com um identificador único por intenção de envio (1 a 255 caracteres ASCII visíveis).

Idempotency-Key: 7f3c1a9e-2b40-4a1e-9c77-8de0f2a51b33

Por que não deduplicamos por conteúdo

Numa conversa real, “ok” e “sim” se repetem o tempo todo, legitimamente. Suprimir a segunda ocorrência seria uma falha invisível — o seu sistema acharia que enviou, o destinatário nunca receberia, e ninguém veria erro nenhum. Duplicata incomoda; falso dedupe some. Por isso a deduplicação é opt-in e a chave é sua intenção, não o conteúdo.

Duas mensagens iguais com chaves diferentes são dois envios legítimos — e devem ser.

O que a chave garante

O escopo da chave é a sua API key, e a janela contratual é de 24 horas.

Estados de entrega

A escada é monotônica — só sobe, nunca desce:

queued → sent → delivered → read → played

Quando falha

{
  "id": "msg_18273",
  "status": "failed",
  "failure": {
    "code": "CHANNEL_DISCONNECTED",
    "retryable": true,
    "at": "2026-08-13T18:12:04.000Z"
  }
}

Decida o retry por failure.retryable, nunca por interpretação do texto. Códigos novos entram de forma aditiva — trate um code desconhecido como falha genérica.

Consultar e reconciliar

# primeira página
curl -H "x-api-key: $NUNTIS_API_KEY" \
  'https://api.nuntis.com.br/v1/messages?limit=50'

# próxima página — repasse `cursor.next` sem interpretar
curl -H "x-api-key: $NUNTIS_API_KEY" \
  'https://api.nuntis.com.br/v1/messages?since=eyJjIjoi...&limit=50'

O statusHistory vem preenchido em GET /v1/messages/{id} e vazio na listagem, de propósito: montar o histórico de cada item multiplicaria as consultas na rota mais chamada do contrato.

Retomar de um ponto no tempo: updatedAfter

Se você não quer varrer a coleção inteira a cada rodada, mande updatedAfter com um instante ISO 8601: a resposta traz as mensagens com timestamp >= updatedAfter. A receita é a mesma da listagem de conversas: guarde o maior timestamp que você viu, reenvie-o e deduplique por id.

# abre a varredura a partir de um instante
curl -H "x-api-key: $NUNTIS_API_KEY" \
  'https://api.nuntis.com.br/v1/messages?updatedAfter=2026-09-01T00:00:00.000Z'

# continua paginando — mantenha os DOIS parâmetros
curl -H "x-api-key: $NUNTIS_API_KEY" \
  'https://api.nuntis.com.br/v1/messages?updatedAfter=2026-09-01T00:00:00.000Z&since=eyJjIjoi...'

O corte é inclusivo de propósito: com um corte exclusivo, a mensagem que caiu no mesmo milissegundo da borda que você guardou seria perdida. É por isso que a deduplicação por id não é opcional — você vai receber de volta o que estava exatamente na borda.

updatedAfter e since se somam. Não remova o filtro ao virar de página: abra a varredura com o instante e continue mandando os dois.

Nuntis — serviço de mensageria multicanal da Devari.