Comunicação na API v1 | Desenvolvedores Steel

Comunicação na API v1

Listar templates do WhatsApp, enviar um template aprovado, ver a fila de conversas aguardando atendimento e acompanhar uma transmissão, com curl, steel CLI e SDK.

Nesta página

Todas as rotas desta página exigem um token com o módulo Comunicação e rodam com as suas permissões na Comunicação. Os exemplos usam $STEEL_URL e $STEEL_TOKEN (veja Antes da primeira chamada).

Operação	Rota	Escopo	CLI	SDK
Listar templates	`GET /api/v1/whatsapp/templates`	`api:read`	`steel zap templates`	`whatsapp.templates()`
Enviar template	`POST /api/v1/whatsapp/messages/template`	`api:write`	`steel zap send`	`whatsapp.sendTemplate()`
Conversas aguardando	`GET /api/v1/whatsapp/conversations/waiting`	`api:read`	—	—
Situação da transmissão	`GET /api/v1/whatsapp/broadcasts/{broadcastId}`	`api:read`	`steel zap broadcast status`	`whatsapp.broadcast()`

A v1 envia só templates (os modelos aprovados pela Meta), que valem a qualquer hora. Texto livre numa conversa fica no aplicativo; na API oficial da Meta ele só é aceito dentro da janela de 24 horas depois da última mensagem do cliente. A fila de conversas sem atendente está em Conversas aguardando atendimento.

Listar templates

Os templates das conexões do workspace. Por padrão, só os aprovados pela Meta.

Parâmetro	Valores
`status`	`APPROVED` (padrão), `PENDING`, `REJECTED`, `PAUSED`, `DISABLED` ou `ALL`
`connectionId`	Só os templates de uma conexão
`limit`, `cursor`	Paginação

curl "$STEEL_URL/api/v1/whatsapp/templates" \
  -H "Authorization: Bearer $STEEL_TOKEN"

{
  "success": true,
  "statusCode": 200,
  "data": {
    "items": [
      {
        "id": "cm2tpl0001",
        "workspaceId": "cm2ws0001",
        "connectionId": "cm2con0001",
        "name": "boas_vindas",
        "language": "pt_BR",
        "category": "MARKETING",
        "status": "APPROVED",
        "components": [
          { "type": "BODY", "text": "Olá, {{1}}! Obrigado pelo contato com a Acme." }
        ],
        "quality": "GREEN",
        "qualityUpdatedAt": "2026-10-10T12:00:00.000Z",
        "statusReason": null,
        "headerFormat": null,
        "headerMediaUrl": null,
        "buttons": [],
        "createdAt": "2026-09-20T12:00:00.000Z",
        "updatedAt": "2026-10-10T12:00:00.000Z"
      }
    ],
    "nextCursor": null
  }
}

steel zap templates                    # aprovados
steel zap templates --status todos     # todos; também pendente, rejeitado, pausado, desativado

const templates = await steel.whatsapp.templates({ status: 'APPROVED' })

Destino	Campos	Conversa usada
Um número	`to` (E.164, `+5511999990000`) e, se houver mais de uma conexão, `connectionId`	Acha ou cria o contato; usa a conversa aberta dele ou abre uma
Um contato do Steel	`contactId` + `connectionId`	A conversa aberta do contato, ou uma nova
Uma conversa	`conversationId`	Ela mesma

curl -X POST "$STEEL_URL/api/v1/whatsapp/messages/template" \
  -H "Authorization: Bearer $STEEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511999990000",
    "templateName": "boas_vindas",
    "language": "pt_BR",
    "components": [
      { "type": "body", "parameters": [{ "type": "text", "text": "Ana" }] }
    ]
  }'

{
  "success": true,
  "statusCode": 201,
  "data": {
    "id": "cm2msg0101",
    "workspaceId": "cm2ws0001",
    "conversationId": "cm2cnv0007",
    "direction": "OUT",
    "type": "TEMPLATE",
    "text": "boas_vindas",
    "mediaUrl": null,
    "status": "SENT",
    "senderUserId": "cm2usr0001",
    "sentByAi": false,
    "replyToMessageId": null,
    "createdAt": "2026-10-18T13:00:00.000Z"
  }
}

[
  { "type": "header", "parameters": [{ "type": "text", "text": "Outubro" }] },
  { "type": "body", "parameters": [{ "type": "text", "parameter_name": "nome", "text": "Ana" }] }
]

steel zap send --template boas_vindas --to 5511999990000 --var 1=Ana --yes
steel zap send --template boas_vindas --contact cm2ctt0003 --connection cm2con0001 --var 1=Ana --yes
steel zap send --template lembrete --conversation cm2cnv0007 --var nome=Ana --yes

const sent = await steel.whatsapp.sendTemplate({
  to: '+5511999990000',
  templateName: 'boas_vindas',
  language: 'pt_BR',
  components: [{ type: 'body', parameters: [{ type: 'text', text: 'Ana' }] }],
})
if (!sent.ok && sent.error.code === 'RATE_LIMITED') {
  // espere sent.error.retryAfterSeconds e tente de novo
}

Erro	Quando e o que fazer
`422 VALIDATION_ERROR` "O workspace tem mais de uma conexão do WhatsApp: informe connectionId."	Envio por `to` sem `connectionId` num workspace com várias conexões conectadas
`422 VALIDATION_ERROR`	Faltou `templateName` ou `language`, número fora do E.164 ou nenhum destino
`404 WHATSAPP_CONNECTION_NOT_FOUND`, `WHATSAPP_CONTACT_NOT_FOUND`, `WHATSAPP_CONVERSATION_NOT_FOUND`	O id não existe neste workspace
`409 WHATSAPP_CONVERSATION_AI_HANDLING`	A IA está atendendo a conversa. Tire a conversa do atendimento da IA no aplicativo e envie de novo
`502 WHATSAPP_PROVIDER_ERROR`	A Meta recusou: template não aprovado nesse idioma, variáveis a mais ou a menos, número sem WhatsApp, ou conexão Z-API. A mensagem traz o motivo quando a Meta informa
`429 RATE_LIMITED`	20 por minuto por conexão, ou o limite do token. Espere o `Retry-After`

curl "$STEEL_URL/api/v1/whatsapp/conversations/waiting?limit=10" \
  -H "Authorization: Bearer $STEEL_TOKEN"

{
  "success": true,
  "statusCode": 200,
  "data": {
    "items": [
      {
        "id": "cm2cnv0001",
        "workspaceId": "cm2ws0001",
        "connectionId": "cm2con0001",
        "contactId": "cm2ctt0003",
        "contactName": "Maria",
        "contactWaId": "5511999990000",
        "contactAvatarUrl": null,
        "status": "NEW",
        "assignedUserId": null,
        "teamId": "cm2tea0001",
        "team": { "id": "cm2tea0001", "name": "Suporte" },
        "aiActive": false,
        "aiHandoff": false,
        "unreadCount": 2,
        "avgSentimentScore": null,
        "lastMessageAt": "2026-10-18T12:00:00.000Z",
        "lastMessagePreview": "Olá, gostaria de um orçamento.",
        "pinned": false,
        "archived": false,
        "closedAt": null,
        "closeReason": null,
        "contactSince": "2026-10-18T11:58:00.000Z",
        "createdAt": "2026-10-18T11:58:00.000Z",
        "updatedAt": "2026-10-18T12:00:00.000Z"
      }
    ],
    "nextCursor": null
  }
}

curl "$STEEL_URL/api/v1/whatsapp/broadcasts/cm2brd0001" \
  -H "Authorization: Bearer $STEEL_TOKEN"

{
  "success": true,
  "statusCode": 200,
  "data": {
    "id": "cm2brd0001",
    "connectionId": "cm2con0001",
    "name": "Promoção de outubro",
    "status": "RUNNING",
    "scheduledAt": null,
    "recipientCount": 1200,
    "sentCount": 830,
    "failedCount": 12,
    "skippedCount": 5,
    "createdAt": "2026-10-18T10:00:00.000Z",
    "updatedAt": "2026-10-18T10:41:00.000Z",
    "recipients": [
      { "id": "cm2rcp0001", "contactId": "cm2ctt0003", "contactName": "Ana", "contactWaId": "5511999990000", "status": "SENT", "errorMessage": null, "sentAt": "2026-10-18T10:01:00.000Z" },
      { "id": "cm2rcp0002", "contactId": "cm2ctt0004", "contactName": null, "contactWaId": "5511988887777", "status": "FAILED", "errorMessage": "Número sem WhatsApp", "sentAt": null }
    ]
  }
}

steel zap broadcast status cm2brd0001

const b = await steel.whatsapp.broadcast('cm2brd0001')
if (b.ok) console.log(`${b.data.sentCount}/${b.data.recipientCount}`)

async function avisarDespacho(telefone: string, nome: string, pedido: string) {
  const sent = await steel.whatsapp.sendTemplate({
    to: telefone,                      // '+5511999990000'
    connectionId: process.env.STEEL_ZAP_CONNECTION,
    templateName: 'pedido_despachado', // aprovado na Meta, com {{1}} e {{2}}
    language: 'pt_BR',
    components: [{
      type: 'body',
      parameters: [
        { type: 'text', text: nome },
        { type: 'text', text: pedido },
      ],
    }],
  })
  if (sent.ok) return sent.data.id
  if (sent.error.code === 'RATE_LIMITED') {
    await new Promise((r) => setTimeout(r, (sent.error.retryAfterSeconds ?? 5) * 1000))
    return avisarDespacho(telefone, nome, pedido)
  }
  throw new Error(`${sent.error.code}: ${sent.error.message}`)
}

Sintoma	O que fazer
A lista de templates vem vazia	Nenhum template aprovado ainda. Veja todos com `status=ALL`; os pendentes dependem da Meta
`502` com um template aprovado	O idioma (`language`) precisa ser exatamente o do template, e o número de variáveis tem de bater com o do corpo
A mensagem não aparece na caixa de entrada	Foi enviada numa conversa nova do contato; procure pelo número. Se a conexão estava desconectada, o envio falha com `502`
O cliente não recebeu, mas o envio deu `201`	O `status` da mensagem muda depois; consulte a conversa no aplicativo. `FAILED` costuma ser número sem WhatsApp ou bloqueio de qualidade da Meta

Comunicação na API v1

Listar templates

Enviar um template

Limites do envio

Erros

Conversas aguardando atendimento

Acompanhar uma transmissão

Receita: aviso de pedido despachado pelo seu ERP

Solução de problemas

Parâmetro	Valores
`connectionId`	Só as conversas de uma conexão
`teamId`	Só a fila de uma equipe
`limit`, `cursor`	Paginação