💬 Shared Inbox do WhatsApp na nova PlataformaMais
1msg official logo

WhatsApp Business API para notificação de agente atribuído

O cenário envia ao cliente um template personalizado pelo WhatsApp quando um ticket de suporte é designado a um especialista.

Visão geral do caso de uso

O cenário envia ao cliente um template personalizado pelo WhatsApp quando um tíquete de suporte é atribuído a um especialista. A mensagem inclui o nome do cliente, número do tíquete e o nome do agente responsável. Um botão com URL estático abre a página do tíquete ou o portal de ajuda.

Exemplo de template

Olá, {{1}}! Um especialista foi designado para sua solicitação #{{2}}: {{3}}. Entraremos em contato com você em breve.

Status do pedido
  • {{1}}
    nome do cliente
  • {{2}}
    número do bilhete ou caso
  • {{3}}
    nome do especialista designado
  • “Status do pedido”
    botão — fixo no template do Meta
WhatsApp Business API for agent assigned notification

Quando usá-lo

Atingir esse cenário quando um ticket de suporte se move da fila para um especialista nomeado e o cliente ainda não tem nenhuma conversa aberta no WhatsApp — apenas um modelo aprovado pode alcançá-los primeiro. Isso se encaixa em equipes de suporte helpdesk e SaaS, níveis premium que apresentam o agente designado, e agências que conectam webhooks de atribuição do Zendesk, Freshdesk ou um CRM.

Menos ansiedade enquanto espera
O nome do cliente, o número do ticket e o nome do especialista chegam como três variáveis no corpo da mensagem no WhatsApp, para que o cliente veja um contato nomeado em vez de uma fila anônima.
Menos mensagens de "quem está cuidando do meu caso?"
A referência do bilhete e o nome do especialista estão no mesmo thread de chat, e o botão de URL estático abre a página do bilhete para qualquer outra coisa que eles precisem verificar.
Sem avisos de atribuição manual
O helpdesk dispara o template no evento de atribuição e o sistema resolve o telefone mais os três campos, assim nenhum agente reescreve a atualização para cada chamado.
Entrega rastreável no helpdesk
O resultado da entrega é registrado após o envio, para que o suporte possa acompanhar no helpdesk ou CRM quando uma notificação falha ou precisa de uma nova tentativa.

Fluxo de Trabalho

  1. Desencadear

    O helpdesk atribui um especialista ao ticket e dispara um evento de atribuição.

    event · triggered

  2. Registrar evento

    O sistema resolve o número de telefone do destinatário e os campos de atribuição.

    phone: "+…"

  3. Construir e enviar

    Uma mensagem de modelo personalizada é construída com três variáveis de corpo e um botão de URL estático.

    POST /sendTemplate

  4. Entregue

    O cliente recebe a notificação do WhatsApp com o número do ticket e o nome do especialista.

    delivered

  5. Status rastreado

    O resultado da entrega é registrado; os erros são tratados de acordo com as regras da plataforma.

    status: "read"

WhatsApp Business API for agent assigned notification

Implementação técnica

Pré-requisitos

  1. Chave da API 1MSG · Como obter a Chave da API
  2. Conta do WhatsApp Business · Como Conectar WABA
  3. Modelo do WhatsApp · Como Aprovar o Modelo do WABA
  4. Consentimento do cliente · Como Gerenciar o Consentimento

Exemplos de código

#!/usr/bin/env bash
set -euo pipefail

# === Configuration (replace "___" placeholders) ===

API_BASE_URL="https://api.1msg.io"        # production 1MSG API base URL
CHANNEL_ID="___"                           # channel ID from 1MSG dashboard
API_TOKEN="___"                            # channel JWT token (Bearer)

TEMPLATE_NAME="___"                        # approved template name
TEMPLATE_NAMESPACE="___"                   # template namespace (required — send fails without it)
TEMPLATE_LANGUAGE="___"                    # template language code, e.g. "en"



# === Test data ===
TEST_PHONE="___"                 # client phone in international format
TEST_CUSTOMERNAME="___"         # {{1}} customer name
TEST_TICKETNUMBER="___"         # {{2}} ticket number
TEST_SPECIALIST="___"         # {{3}} specialist name

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"

for pair in "CHANNEL_ID=$CHANNEL_ID" "API_TOKEN=$API_TOKEN" \
            "TEMPLATE_NAME=$TEMPLATE_NAME" "TEMPLATE_NAMESPACE=$TEMPLATE_NAMESPACE" \
            "TEMPLATE_LANGUAGE=$TEMPLATE_LANGUAGE" "TEST_PHONE=$TEST_PHONE" \
            "TEST_CUSTOMERNAME=$TEST_CUSTOMERNAME" \
            "TEST_TICKETNUMBER=$TEST_TICKETNUMBER" \
            "TEST_SPECIALIST=$TEST_SPECIALIST"; do
    val="${pair#*=}"
    if [ -z "$val" ] || [ "$val" = "___" ]; then
        echo "Missing configuration value: ${pair%%=*}" >&2
        exit 1
    fi
done

if [ -z "$PHONE_NORM" ]; then
    echo "Error: phone number has no digits after normalization" >&2
    exit 1
fi

URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendTemplate"

# params carries body ONLY. Button text is fixed in the Meta template — no button param.

# {{1}} customer name → ${TEST_CUSTOMERNAME}
# {{2}} ticket number → ${TEST_TICKETNUMBER}
# {{3}} specialist name → ${TEST_SPECIALIST}
read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "template": "${TEMPLATE_NAME}",
  "namespace": "${TEMPLATE_NAMESPACE}",
  "language": { "policy": "deterministic", "code": "${TEMPLATE_LANGUAGE}" },
  "params": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "${TEST_CUSTOMERNAME}" },
        { "type": "text", "text": "${TEST_TICKETNUMBER}" },
        { "type": "text", "text": "${TEST_SPECIALIST}" }
      ]
    }

  ]
}
JSON

RESPONSE="$(curl -s -w '\n%{http_code}' -X POST "$URL" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${API_TOKEN}" \
    -d "$PAYLOAD")"

HTTP_CODE="$(printf '%s' "$RESPONSE" | tail -n1)"
BODY="$(printf '%s' "$RESPONSE" | sed '$d')"

case "$BODY" in
    *'"sent":true'*) ok=1 ;;
    *) ok=0 ;;
esac

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ] && [ "$ok" -eq 1 ]; then
    echo "Message sent to client."
    echo "API response: $BODY"
else
    echo "Send failed. HTTP status: $HTTP_CODE" >&2
    echo "$BODY" >&2
    exit 1
fi

Status de resposta e entrega

HTTP 2xx e JSON "sent": true significam que 1MSG aceitou a mensagem para envio — não que ela já chegou no telefone do cliente. Salve o campo id (parece wamid.…) para correlacionar as callbacks de entrega.

200 Entendi.Resposta
{
  "sent": true,
  "id": "wamid.HBgLMzgwNjM5...",
  "message": "Message accepted for delivery"
}
  • sent

    Aceito para envio — não ainda no telefone do cliente

  • id

    Armazene isso; os callbacks de entrega e hookInfo são baseados nisso.

A entrega em si chega mais tarde, como uma chamada de retorno separada. Registre um webhook (POST …/webhook) e 1MSG POSTs atualizações de status para seu endpoint HTTPS em uma carga útil hooks[] de nível superior.

200 Claro!Webhook de status de entrega — payload recebido
{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}
  • status

    enviado, entregue, lido — ou um status de falha quando aplicável

  • id

    Correla o callback com o id retornado pela chamada de envio

  • timestamp

    Segundos Unix, como uma string

Se você preferir não receber chamadas de retorno, consulte GET {base}/{channel}/hookInfo?messageId=<id> em vez disso. Na prática, a entrega geralmente é concluída em segundos — mas o contrato da API não garante isso, então nunca bloqueie um fluxo esperando por isso.

Erros comuns

StatusRespostaCausa
200Message was not sent: template is not definednamespace, template or language missing from the request body.
200template name (…) does not exist in <language>The template is approved in a different language than the one requested.
200Message was not sent: provide chatId, phone, bsuid, or usernameNo recipient the channel could resolve.
403access deniedThe token is wrong, or belongs to a different channel than the URL.
429too many requests. please try laterThe channel is over its send rate.

Perguntas Frequentes

Sim — mensagens de WhatsApp de início frio exigem um template aprovado pelo Meta.

Relacionado

Serviço ao Cliente
WhatsApp Business API para suporte — reação e confirmações
Este cenário combina sendReaction e readMessage durante a janela de atendimento ao cliente de 24 horas.
Serviço ao Cliente
WhatsApp Business API para suporte — botões interativos
Este cenário envia uma mensagem interativa com o sendButton durante a janela de atendimento ao cliente de 24 horas.
Serviço ao Cliente
WhatsApp Business API para resposta de sessão — solicite mais.
Este cenário envia uma mensagem de texto livre pelo WhatsApp com sendMessage dentro da janela de atendimento ao cliente de 24 horas.
Serviço ao Cliente
WhatsApp Business API para notificação de resolução
O cenário envia um template personalizado pelo WhatsApp quando o ticket de suporte do cliente é resolvido.
Serviço ao Cliente
WhatsApp Business API — repasse ao especialista com contato
Este cenário envia um cartão de contato do WhatsApp com sendContact durante a janela de atendimento ao cliente de 24 horas.
Serviço ao Cliente
WhatsApp Business API para lembrete de resposta pendente
O cenário envia ao cliente um template personalizado de WhatsApp quando o suporte está bloqueado aguardando sua resposta.
Serviço ao Cliente
WhatsApp Business API para notificação de mudança de serviço
O cenário envia ao cliente um modelo personalizado de WhatsApp quando a empresa muda como um serviço ou processo funciona para eles.
Serviço ao Cliente
WhatsApp Business API para confirmação de recebimento
O cenário envia ao cliente um modelo de WhatsApp personalizado logo após a submissão de um formulário de aplicação ou solicitação.

Crie para o WhatsApp em horas
sem complicações de infraestrutura