Todos os produtos
Search
Central de documentação

Chat App Message Service:Habilidade de envio de mensagens do Chat App

Última atualização: Aug 28, 2026

Envie mensagens pelo WhatsApp, consulte modelos e gerencie sessões diretamente de um agente de IA, sem alternar entre consoles ou construir requisições de API manualmente.

Pré-requisitos

  1. Obtenha um AccessKey ID e um AccessKey Secret para uma subconta da Alibaba Cloud. A conta principal deve criar um usuário no Resource Access Management (RAM) console e conceder as permissões necessárias do Chat App Message Service (CAMS).

  2. Ative o Chat App Message Service console e conclua as etapas a seguir:

    • Vincule uma Conta Comercial do WhatsApp (WABA).

    • Registre e obtenha aprovação para o número de telefone do remetente (From).

    • Crie e obtenha aprovação para os modelos de mensagem. Esta etapa é obrigatória para o envio de mensagens com modelo.

Principais capacidades e vantagens

Abrange cenários comuns de negócios, como notificações de pedidos internacionais, campanhas de marketing e acompanhamento de atendimento ao cliente.

Capacidade

Descrição

Envio de mensagens com modelo

Envia mensagens de modelo do WhatsApp fora da janela de sessão de 24 horas. Oferece suporte à substituição de variáveis para casos de uso como notificações de marketing, atualizações de status de pedidos, códigos de verificação e lembretes logísticos.

Envio de mensagens personalizadas

Permite enviar mensagens de formato livre dentro da janela de sessão de 24 horas. Compatível com sete tipos de mensagem: texto, imagem, vídeo, áudio, documento, interativa e localização.

Consulta da lista de modelos

Filtra modelos por status de aprovação, tipo ou idioma, permitindo que o agente selecione automaticamente ou exiba opções ao usuário.

Consulta de detalhes do modelo

Recupera a estrutura de variáveis de um modelo específico para que o agente possa orientar o usuário no preenchimento dos parâmetros um a um, evitando incompatibilidades de quantidade e formato.

Principais vantagens:

  • Envio conversacional de mensagens: Consulte modelos, preencha variáveis e envie mensagens usando linguagem natural em ferramentas de agentes como Claude Code, Qwen Coder e OpenClaw — sem precisar acessar o console.

  • Redução do custo de construção de parâmetros: Chamadas de API tradicionais exigem um JSON Content estritamente formatado, e qualquer erro de formato pode causar falhas. O agente constrói automaticamente um JSON válido e auxilia na correspondência das variáveis.

  • Diagnóstico automatizado de erros: Inclui diagnósticos integrados e sugestões de solução para códigos de erro comuns. Por exemplo, se ocorrer um erro SessionWindowExpired, a habilidade muda automaticamente para o fluxo de mensagens com modelo. Caso as permissões do RAM sejam insuficientes, ela orienta você durante o processo de solicitação de permissão.

  • Confirmação pré-envio: Todos os parâmetros personalizáveis (From, To, modelo, variáveis, JSON Content) exigem confirmação explícita do usuário antes do envio, garantindo a entrega precisa das mensagens.

Recursos compatíveis:

  • Consulte listas e detalhes de modelos de forma conversacional para encontrar modelos disponíveis e suas estruturas de variáveis.

  • Envie mensagens com modelo e personalizadas automaticamente para alcançar usuários fora da janela de sessão de 24 horas.

  • Detecte a expiração da janela de sessão e alterne automaticamente para o fluxo de mensagens com modelo.

  • Utilize modelos em vários idiomas (como en, zh_CN e zh_HK).

  • Gerencie cenários multilocatários para fornecedores independentes de software (ISVs) por meio do parâmetro --cust-space-id.

Métodos de instalação

Instale pelo Alibaba Cloud Skill Marketplace (recomendado)

Acesse o Alibaba Cloud Skill Marketplace, pesquise por "ChatApp Message Sending" e instale-o.

Instale pelo ClawHub

Acesse a plataforma ClawHub e pesquise por "alibabacloud-chatapp-message-send" para visualizar a documentação da habilidade e instalá-la.

Outros métodos de instalação

Instalação no Claude Code

Consulte a documentação oficial do Claude Code.

Descompacte o pacote da habilidade baixado e mova-o para o diretório de habilidades do Claude Code:

  • Para escopo global (todos os projetos): Mova a habilidade para o diretório ~/.claude/skills/.

  • Para escopo de nível de projeto (apenas o projeto atual): Mova a habilidade para o diretório project_root/.claude/skills/.

Após mover o diretório, reinicie o Claude Code para que as alterações entrem em vigor.

Instalação no OpenClaw

Descompacte o pacote da habilidade baixado e copie o caminho do diretório da habilidade. No OpenClaw, insira o caminho e diga: "Help me install the skill in this directory." Aguarde uma mensagem de confirmação antes de usar a habilidade.

Configuração do ambiente

Aliyun CLI >= 3.3.3

Execute aliyun version para verificar sua versão atual. Se o Aliyun CLI não estiver instalado ou a versão for muito antiga:

# For macOS or Linux, install or upgrade to the latest version:
curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash

# Verify the version (must be >= 3.3.3)
aliyun version
Importante

Antes de fazer qualquer chamada de CLI, ative a instalação automática de plug-ins e o ai-mode.

aliyun configure set --auto-plugin-install true
aliyun plugin update
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send"
Aviso

Sempre desative o ai-mode quando sua sessão terminar, seja após a conclusão bem-sucedida da tarefa ou em caso de erro. Execute aliyun configure ai-mode disable antes de sair.

Instale o plug-in CAMS

aliyun plugin install --names aliyun-cli-cams

Verifique credenciais

Aviso

Siga estas práticas para proteger suas credenciais.

  • Não exiba nem imprima valores de AccessKey ID ou AccessKey Secret no terminal ou no chat.

  • Não insira um AccessKey ID ou AccessKey Secret diretamente na conversa ou na linha de comando.

  • Não use aliyun configure set com credenciais em texto simples.

  • Use aliyun configure list para verificar se existe um perfil de credencial válido.

aliyun configure list

Verifique na saída se há um perfil válido (AccessKey (AK), Security Token Service (STS) ou OAuth). Se não existir nenhum perfil válido, não prossiga. Obtenha uma credencial no RAM console e configure-a fora da sessão usando aliyun configure ou variáveis de ambiente antes de continuar.

Permissões do RAM

As seguintes ações do RAM são obrigatórias:

API

Ação

Descrição

SendChatappMessage

cams:SendChatappMessage

Enviar uma mensagem

ListChatappTemplate

cams:ListChatappTemplate

Consultar lista de modelos

GetChatappTemplateDetail

cams:GetChatappTemplateDetail

Consultar detalhes do modelo

ListChatappMessage

cams:ListChatappMessage

Consultar lista de mensagens

JSON da política de permissão mínima:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cams:SendChatappMessage",
        "cams:ListChatappTemplate",
        "cams:GetChatappTemplateDetail",
        "cams:ListChatappMessage"
      ],
      "Resource": "*"
    }
  ]
}

Casos de uso

Notificações de pedidos internacionais

Notificações de envio, atualizações logísticas e confirmações de pagamento são comuns no comércio transfronteiriço.

Anteriormente, a equipe operacional precisava encontrar o modelo correto, preencher variáveis e preparar números de telefone antes de enviar mensagens por um console ou script. Com esta habilidade, você informa suas necessidades ao agente, e ele cuida da correspondência de modelos, preenchimento de variáveis, envio de mensagens e relatório de resultados.

Campanhas de marketing

No marketing internacional, o WhatsApp é frequentemente usado para anúncios de novos produtos, lembretes promocionais e reengajamento de membros.

As mensagens com modelo do WhatsApp devem ser pré-aprovadas, e a habilidade não reduz o período de revisão de modelos da Meta. No entanto, assim que um modelo é aprovado, o agente pode ajudar você a usá-lo com mais eficiência. Ele também valida formatos de números de telefone e correspondências de modelos, gerencia listas de clientes, faz a correspondência de variáveis, envia mensagens sequencialmente uma a uma e revisa os resultados.

Acompanhamento de atendimento ao cliente

A janela de sessão de 24 horas é uma regra crítica no atendimento ao cliente. Depois que um cliente inicia uma conversa, a empresa pode enviar mensagens de formato livre dentro dessa janela. Fora dela, são necessárias mensagens com modelo.

A habilidade ajuda o agente a determinar se deve usar uma mensagem de formato livre ou com modelo, recomendando o método apropriado. Isso reduz a carga cognitiva da equipe de atendimento e ajuda a prevenir falhas de envio.

Perguntas frequentes

Quais ferramentas de agente de IA esta habilidade suporta?

Atualmente, oferece suporte a ferramentas que seguem o padrão Agent Skills, como Claude Code, Cursor, OpenClaw, Qoderwork e Wukong. O suporte a mais plataformas está em desenvolvimento.

Qual é a diferença entre as capacidades da habilidade e as do console?

A habilidade suporta o envio de mensagens com modelo, o envio de mensagens personalizadas, a consulta de listas de modelos e a consulta de detalhes de modelos. A criação de modelos e outros recursos do console de mensagens ainda não são compatíveis e continuam exigindo operação manual pelo console.

Posso enviar mensagens sem registrar uma conta?

Não. Você deve registrar uma conta Alibaba Cloud, ativar o Chat App Message Service, vincular sua WABA e concluir o registro e a aprovação do seu número de telefone remetente e dos modelos de mensagem.

Usuários individuais podem usar este service?

Usuários individuais podem usar o service apenas se fornecerem qualificações comerciais válidas. Não há suporte para o uso do service com qualificações pessoais.

As variáveis de modelo precisam ser preenchidas em um formato específico?

Sim. As variáveis de modelo devem ser preenchidas em ordem numérica (por exemplo, 1=value1 2=value2 3=value3). O agente orientará você na confirmação de cada uma para evitar incompatibilidades de quantidade ou formato.

Quais modelos podem ser usados para enviar mensagens?

Você pode usar qualquer modelo com status "Approved" e idioma correspondente ao do usuário alvo. É possível consultar modelos aprovados usando o comando list-chatapp-template --audit-status pass.

Quantas mensagens posso enviar de uma vez?

Se você tiver vários números de telefone, poderá enviar para múltiplos usuários. Forneça ao agente a lista de números de telefone de destino.

Mensagens personalizadas só podem ser enviadas dentro de 24 horas?

Sim. Mensagens personalizadas do WhatsApp só podem ser enviadas dentro de 24 horas após a última mensagem do usuário. Após esse período, você receberá um erro SessionWindowExpired, e o agente mudará automaticamente para o fluxo de mensagens com modelo.

Códigos de erro comuns

Código de erro

Descrição

Solução

InvalidParameter.FromOnlyNumeric

O número de telefone contém um sinal "+".

A API exige que o número de telefone esteja em formato apenas numérico. Remova o sinal + inicial. Exemplo: 8613867404376.

DetailError.TemplateNotExist

O modelo não existe.

Verifique o template-code e o biz-language.

TemplateParamInvalid

A variável do modelo é inválida.

Verifique se a quantidade e o formato das variáveis correspondem ao modelo.

SessionWindowExpired

A janela de sessão de 24 horas expirou.

Mude para o fluxo de mensagens com modelo.

InvalidParameter.FromError

Não foi possível encontrar o valor de from.

Verifique se o número de telefone --from está registrado na WABA e aprovado.

Forbidden.RAM

Permissões do RAM insuficientes.

Use a habilidade ram-permission-diagnose para obter as permissões ausentes.

InvalidAccessKeyId.NotFound

O AccessKey ID é inválido.

Verifique o AccessKey ID.

SignatureDoesNotMatch

O AccessKey Secret está incorreto.

Verifique o AccessKey Secret.

Quando um comando falha devido a permissões insuficientes do RAM, a habilidade identifica as permissões ausentes e orienta você durante o processo de solicitação. Após confirmar as alterações, o comando original é retomado automaticamente.

Recursos relacionados