Servidor MCP para gerenciar conversas do WhatsApp Business Platform a partir de assistentes de IA como Meta Muse e Claude
Continue no assistente de IA que você já usa. Conecte-o ao TimelinesAI para ler suas conversas do WhatsApp Business Platform, responder clientes, enviar modelos aprovados e atribuir e etiquetar conversas para sua equipe.
O servidor MCP do TimelinesAI funciona com qualquer assistente de IA que aceite servidores MCP remotos com login via OAuth. Não há software para instalar, nem servidor para manter, nem senha para compartilhar. O assistente só pode fazer o que a sua função no TimelinesAI permite.
O que o conector pode fazer
- Ler conversas, o histórico de mensagens e o status das mensagens em todos os seus números do WhatsApp Business Platform
- Responder com texto livre enquanto a janela de 24 horas do cliente estiver aberta
- Enviar modelos aprovados pela Meta e iniciar novas conversas com um modelo
- Atribuir e remover a atribuição, abrir e fechar conversas, e adicionar ou remover etiquetas
- Reagir a mensagens e ver os membros da sua equipe e os seus modelos
O que você precisa
- Uma conta no TimelinesAI. Contas novas começam com um teste grátis de 10 dias, sem cartão de crédito.
- Pelo menos um número do WhatsApp Business Platform (Cloud API) conectado ao seu espaço de trabalho. Novo no WhatsApp Business Platform? Conecte e ative um número do WhatsApp Business no Meta Business Portfolio.
- Pelo menos um modelo aprovado, se você quiser que o assistente inicie novas conversas ou envie mensagens a clientes fora da janela de 24 horas.
Como configurar
Passo 1: Adicione o conector.
No seu assistente de IA, adicione um novo conector (ou servidor MCP personalizado) e cole
https://mcp.services.timelines.ai/mcp/waba.Passo 2: Entre com o TimelinesAI.
O assistente abre a página de login do TimelinesAI. Entre na sua conta ou crie uma.
Passo 3: Aprove o acesso.
Revise as permissões na página “Authorize timelines-mcp?” e clique em Authorize.
Passo 4: Faça sua primeira pergunta.
Experimente “Liste meus números do WhatsApp Business” ou “Mostre as conversas que estão aguardando resposta”.
Detalhes da conexão
| Configuração | Valor |
|---|---|
| URL do servidor MCP | https://mcp.services.timelines.ai/mcp/waba |
| Transporte | Streamable HTTP |
| Login | OAuth 2.1 com PKCE (S256) e registro dinâmico de clientes |
| Servidor de autorização | https://mcp.services.timelines.ai |
| Escopos | openidchats:readchats:writemessages:readmessages:writelabels:readlabels:writeaccounts:readworkspace:readtemplates:read |
Ferramentas (18)
As ferramentas de leitura apenas consultam dados. As de escrita alteram uma conversa dentro do TimelinesAI. As de escrita sensível enviam algo que o seu cliente vê, e a Meta cobra pelo envio de modelos.
| Ferramenta | O que faz | Acesso |
|---|---|---|
waba_accounts | Lista os números do WhatsApp Business Platform dos quais você pode enviar | Leitura |
waba_list_chats | Lista as conversas que você pode ver, com filtros (por exemplo, por número de telefone) | Leitura |
waba_chat_details | Mostra uma conversa: se a janela de 24 horas está aberta, o responsável, as etiquetas e o número de envio | Leitura |
waba_chat_history | Mostra as mensagens de uma conversa, das mais recentes para as mais antigas | Leitura |
waba_message_details | Mostra uma mensagem, incluindo o motivo se ela falhou | Leitura |
waba_templates | Lista os modelos de mensagem que você pode usar | Leitura |
waba_template_details | Mostra um modelo: conteúdo, variáveis, status e os números dos quais pode ser enviado | Leitura |
workspace_team | Lista os colegas de equipe, para que uma conversa possa ser atribuída a um deles | Leitura |
waba_chat_open | Reabre uma conversa fechada | Escrita |
waba_chat_close | Fecha uma conversa | Escrita |
waba_chat_assign | Atribui uma conversa a um colega de equipe | Escrita |
waba_chat_unassign | Remove o responsável de uma conversa | Escrita |
waba_chat_set_label | Adiciona uma etiqueta a uma conversa | Escrita |
waba_chat_remove_label | Remove uma etiqueta de uma conversa | Escrita |
waba_chat_send_message | Envia uma resposta de texto livre numa conversa existente, apenas enquanto a janela de 24 horas estiver aberta | Escrita sensível |
waba_chat_send_template | Envia um modelo aprovado numa conversa existente | Escrita sensívelA Meta cobra pelos modelos |
waba_start_chat | Inicia uma nova conversa com um número de telefone usando um modelo aprovado | Escrita sensívelA Meta cobra pelos modelos |
waba_message_react | Adiciona ou remove uma reação com emoji numa mensagem | Escrita sensívelO cliente vê |
Cada ferramenta é marcada como somente leitura ou como uma que faz alterações, para que os assistentes de IA possam pedir sua confirmação antes de executar uma escrita.
Entradas das ferramentas
Cada ferramenta retorna a resposta JSON da API do TimelinesAI para essa ação. As entradas obrigatórias estão em negrito. O assistente obtém primeiro os ids com as ferramentas de listagem (por exemplo, o id de uma conversa com waba_list_chats).
| Ferramenta | Entradas |
|---|---|
waba_accounts | Nenhuma |
waba_list_chats | Todas opcionais: waba_account_id, responsible (e-mail do membro da equipe), closed (true ou false), whatsapp_phone, with_msg (inclui a última mensagem), page (50 conversas por página) |
waba_chat_details | chat_id |
waba_chat_history | chat_id. Opcionais: from_me, after e before (data ou data e hora ISO), after_message e before_message (id da mensagem), sorting_order (asc ou desc), page, size |
waba_message_details | message_uid |
waba_templates | page opcional |
waba_template_details | template_id |
workspace_team | Nenhuma |
waba_chat_openwaba_chat_closewaba_chat_unassign | chat_id |
waba_chat_assign | chat_id, user_email (um membro da equipe de workspace_team) |
waba_chat_set_labelwaba_chat_remove_label | chat_id, label |
waba_chat_send_message | chat_id, text |
waba_chat_send_template | chat_id, name e language de um modelo aprovado. variables opcional: listas header e body, na ordem do modelo |
waba_start_chat | waba_account_id, phone (formato internacional com + no início), name e language de um modelo aprovado. variables opcional, como acima |
waba_message_react | message_uid, reaction (um emoji, ou um valor vazio para removê-la) |
Erros e limites
Quando uma chamada falha, a ferramenta retorna um resultado de erro com o status HTTP, a mensagem da API do TimelinesAI e, quando houver, um código de erro. O assistente pode então explicar o que aconteceu e o que fazer em seguida.
| Status | O que significa | O que fazer |
|---|---|---|
| 400, 409, 422 | A solicitação foi rejeitada, por exemplo por falta de uma entrada ou por um número de telefone no formato errado | Corrija a entrada e tente novamente |
| 401 | O login não é mais válido | Reconecte o conector e faça login no TimelinesAI novamente |
| 403 | A função ou o plano do usuário não permite esta ação | Peça a um proprietário ou administrador do espaço de trabalho |
| 404 | A conversa, a mensagem ou o modelo não foi encontrado | Encontre o id correto com as ferramentas de listagem |
| 429 | Solicitações demais | Aguarde um momento e tente novamente |
| 5xx, ou sem resposta em 15 segundos | Problema temporário no TimelinesAI | Tente novamente mais tarde |
- Janela de 24 horas: se a janela estiver fechada, uma resposta de texto livre é rejeitada. Envie um modelo aprovado em vez disso.
waba_chat_detailsewaba_list_chatsmostram se a janela está aberta. - Entrega: um envio bem-sucedido significa que a Meta aceitou a mensagem. Se a entrega falhar depois,
waba_message_detailsmostra o motivo. - Sem envios duplicados: as ferramentas de envio não são repetidas automaticamente. Se um envio expirar, verifique
waba_chat_historyantes de enviar de novo, para que o cliente não receba a mensagem duas vezes. - Limites de taxa: o conector não adiciona um limite próprio. Os limites de mensagens da Meta para o seu número do WhatsApp Business Platform continuam valendo para mensagens de modelo.
O que o assistente pode ver
O assistente age como o usuário do TimelinesAI que fez login, com as permissões desse usuário. Ele nunca vê mais do que esse usuário pode ver no TimelinesAI.
- Proprietários e administradores veem todos os números do WhatsApp Business Platform do espaço de trabalho e todas as conversas deles.
- Supervisores de equipe e membros da equipe veem os números cuja equipe é a deles, e as conversas desses números.
- Agentes veem os números atribuídos a eles, e as conversas desses números.
- Colaboradores veem apenas as conversas atribuídas a eles. Podem responder nelas, mas não podem iniciar novas conversas.
- Conversas atribuídas: qualquer pessoa atribuída a uma única conversa pode vê-la e responder nela. Isso não dá acesso ao restante desse número.
Regras de mensagens
- Dentro da janela de 24 horas (o cliente escreveu nas últimas 24 horas), o assistente pode enviar respostas de texto livre.
- Fora da janela, ou numa conversa nova, só é possível enviar modelos aprovados pela Meta. Um modelo não reabre a janela para texto livre.
- Modelos com cabeçalho de mídia (imagem, vídeo ou documento) ainda não podem ser enviados pelo conector. Use modelos com variáveis de texto.
- Entrega: um envio bem-sucedido significa que a Meta aceitou a mensagem. A entrega ainda pode falhar depois, e o assistente pode verificar o motivo.
Preços
O uso do conector está incluído em todos os planos do TimelinesAI sem custo adicional. A Meta cobra pelas mensagens de modelo segundo suas tarifas padrão do WhatsApp Business Platform, e o assistente avisa você antes de enviar uma.
Privacidade e segurança
- O login usa OAuth, então o seu assistente de IA nunca vê a sua senha do TimelinesAI.
- O assistente só pode usar os dados que o usuário conectado pode acessar, dentro dos escopos acima.
- Para desconectar, remova o conector no seu assistente de IA.
- Veja o Aviso de privacidade deste conector (em inglês) e os Termos. Ajuda: support@timelines.ai.
Perguntas frequentes sobre o servidor MCP do WhatsApp Business Platform
Última atualização: