Espalhe o espírito natalino com os agentes de IA e as ferramentas de mensagens do Vonage MCP

Automatize o envio de mensagens personalizadas pelo WhatsApp, RCS e SMS usando agentes de IA e o servidor MCP da Vonage!

Introdução

À medida que sua empresa cresce, as mensagens padronizadas simplesmente não são mais suficientes. Alguns usuários preferem SMS. Outros esperam receber mensagens pelo WhatsApp. E, com a crescente adoção do RCS, oferecer suporte a vários canais está se tornando essencial. O desafio? Personalizar as mensagens em todos os canais, idiomas e preferências sem precisar criar e manter uma infraestrutura complexa.

Você consegue adivinhar a solução? IA! Ao utilizar assistentes de IA, como o Windsurf ou o Cursor, dentro do seu IDE, você pode delegar tarefas de comunicação repetitivas e que exigem muita lógica a um agente. Esse é um caso de uso ideal para mensagens multicanais assistidas por IA. 

Neste tutorial, você aprenderá a integrar um agente de IA ao servidor MCP da Vonage para enviar mensagens personalizadas de fim de ano, adaptadas ao canal, com base nas preferências do contato. Usando um arquivo CSV simples, você configurará a IA para ler as preferências de mensagens, escolher o canal de entrega correto, lidar com a lógica de fallback e até mesmo localizar as saudações por idioma. Seja para dizer Feliz Hanukkah ou Feliz Natal, esse fluxo de trabalho permite que você amplie seu alcance sem precisar desenvolver um aplicativo completo.

Screen recording of an AI agent in Windsurf reading a CSV file of holiday contacts and generating personalized messages using the Vonage Tooling MCP Server, with some data fields obscured for privacy.

Entendendo nosso agente de IA

Se você ainda não conhece o Protocolo de Contexto de Modelo (MCP) ou os agentes de IA, confira nossa postagem introdutória: Apresentando o MCP: a IA se une às comunicações programáveis com a Vonage

Uma breve recapitulação: os servidores MCP permitem que agentes de IA (como o Windsurf ou o Claude) descubram e utilizem com segurança funcionalidades de desenvolvedor, chamadas ferramentas, sem precisar codificar manualmente cada chamada de API. Em vez de escrever a lógica de integração do zero, o servidor disponibiliza recursos como Enviar um SMS ou Verificar meu saldo, e o agente decide como e quando usá-las.

Este tutorial utiliza o Servidor MCP do Vonage Tooling, que disponibiliza um conjunto de ferramentas da Vonage às quais seu agente pode acessar diretamente do seu IDE. Esta publicação utiliza estas cinco ferramentas de mensagens:

• whatsapp-send-text

• whatsapp-send-text-with-sms-failover

• rcs-send-text

• rcs-send-text-with-sms-failover

• sms

O agente de IA utiliza essas ferramentas para identificar as preferências de um contato, escolher o canal adequado (por exemplo, WhatsApp na Europa, SMS nos EUA) e enviar uma mensagem personalizada. Se o canal preferido não funcionar, o servidor recorre automaticamente ao SMS por meio de uma lógica de failover integrada.

Essas ferramentas oferecem uma função unificada de mensagens que formata números de telefone, verifica credenciais e encaminha a mensagem para o canal correto. Se o canal preferencial não funcionar, é possível recorrer automaticamente ao SMS

Cada canal possui seu próprio wrapper leve sendWhatsAppText, sendRCSText, sendSMSText), e cada um está registrado como uma ferramenta MCP que o agente pode detectar e usar diretamente.

Agora vamos configurar nosso agente para usar essas ferramentas!

Veja a lógica completa >> Confira sendChannelMessage() e os registros das ferramentas em index.ts.

Pré-requisitos

• Account do WhatsApp Business: você precisará ter um Account do WhatsApp Business ativado na sua conta da API da Vonage.

• Um agente registrado Agente registrado do RCS Business Messaging (RBM)

• Um celular com o RCS ativado para testes

• IDE com recursos de agente de IA, como VS Code, Cursorou Windsurf.

  • Este tutorial utilizará o Windsurf.

Passo 1: Criar uma aplicação da Vonage com RCS e WhatsApp

Você pode pensar que nosso agente é capaz de criar uma aplicação da Vonage. Infelizmente, ainda não. Mas nosso servidor é de código aberto, então você pode nos ajudar e adicionar essa funcionalidade por meio de um PR! Por enquanto, você terá que criar sua aplicação pelo Painel da Vonage ou pela CLI.

Requisitos para o seu aplicativo

1. Ative os recursos do Messages. Você pode adicionar URLs fictícias para os webhooks.

2. Gere uma chave pública e uma chave privada; você as utilizará mais tarde para configurar seu servidor MCP.

3. Vincule seus accounts do WhatsApp e do RCS

Screenshot from the Vonage API Dashboard showing RCS and WhatsApp accounts linked to an application under the 'Link external accounts' tab, with options to unlink each.

Etapa 2: Criar um arquivo CSV com os contatos

O que é ótimo nos assistentes de IA integrados ao IDE é que eles conseguem ler qualquer arquivo que esteja aberto. Para aplicativos de produção, é recomendável criar um projeto completo com algum tipo de banco de dados. Para este caso de uso divertido, basta criar um arquivo CSV simples e abri-lo no Windsurf:

touch holiday_contacts.csv
windsurf holiday_contacts.csv

No arquivo CSV, adicione contatos com seus números de telefone, preferências de comunicação e feriados preferidos. Você também pode incluir mais informações sobre cada contato para ajudar o Agente de IA a gerar uma mensagem mais personalizada; incluí o idioma preferido.

Aqui está um exemplo de arquivo CSV; substitua pelos números de telefone que você quiser testar:

name,phone,rcs?,whatsapp?,preferred_holiday,preferred_language
Boris Shomris,11233214567,no,yes,hanukkah,hebrew
Alberto Roberto,34123321456,yes,yes,christmas,spanish
Henry Mulenberry,11233214567,yes,no,new_year,english
Sasha Pasha,44123321457,no,yes,kwanza,english
Tenzin Kenzin,86123321458,yes,no,bodhi_day,hindi

Etapa 3: Configure seu servidor MCP

Agora você precisará conceder ao Cascade no Windsurf (ou ao seu agente do Cursor/VS Code) acesso ao servidor do Vonage Tooling. Abra o painel do Cascade (option+command+B). Clique no ícone do plugin e, em seguida, clique no ícone de configurações. Você também pode abrir o arquivo mcp_config.json diretamente. Por padrão, ele está em Users>{your_user}>.codeium>windsurf>mcp.json.

Nesse ponto, adicione o servidor Vonage Tooling ao seu objeto mcpServers:

{
  "mcpServers": {
    "vonage-tooling": {
      "command": "npx",
      "args": ["-y", "@vonage/vonage-mcp-server-api-bindings"],
      "env": {
        "VONAGE_API_KEY": "your_api_key_here",
        "VONAGE_API_SECRET": "your_api_secret_here", 
        "VONAGE_APPLICATION_ID": "your_application_id_here",
        "VONAGE_PRIVATE_KEY64": "your_private_key_base64_here",
        "VONAGE_WHATSAPP_NUMBER": "+1234567890",
        "RCS_SENDER_ID": "YourBrandName",
        "VONAGE_VIRTUAL_NUMBER": "+1234567890"
      }
    }
  }
}

• Encontre o seu API_KEY e API_SECRET nas página de configurações da API no Painel da Vonage.

• O APPLICATION_ID, VONAGE_WHATSAPP_NUMBERe RCS_SENDER_ID podem ser encontrados na página do aplicativo que você criou na etapa 1. Você pode reutilizar seu VONAGE_WHATSAPP_NUMBER valor para o VONAGE_VIRTUAL_NUMBER valor, que é usado para enviar SMS.

• A chave privada que geramos anteriormente ainda não está no formato base64. Você precisará convertê-la usando a ferramenta “Private Key to Environment Variable” e, em seguida, colá-la em VONAGE_PRIVATE_KEY64. 

Depois de adicionar todas as variáveis de ambiente, reinicie o Windsurf. Ao abrir o Cascade, você deverá ver que o servidor Vonage-Tooling está disponível com as ferramentas. Que legal! Você pode ver que eu também tenho o Servidor de Documentação da Vonage disponível.

 Confirmation in Windsurf that the Vonage Tooling MCP Server is active and connected, as seen in the Cascade panel.

Etapa 4: Teste com seu agente de IA

Depois de preparar seu arquivo CSV com os contatos e conceder acesso ao Cascade às ferramentas da Vonage, pronto! Agora é hora de experimentar diferentes mensagens de início de conversa e ver o quanto seu Agente de IA pode ser envolvente, sincero ou engraçado.

Example of a personalized holiday greeting sent via WhatsApp using the Vonage MCP Tooling Server, customized with name and Spanish-language message content.

Experimente diferentes comandos para testar o comportamento deles. Por exemplo, tive um usuário de teste que tinha tanto o RCS quanto o WhatsApp configurados como “sim” no CSV, mas apenas o número do RCS dele funcionou de fato. O comportamento esperado deveria ser “tentar o RCS, depois tentar o WhatsApp e, só então, enviar o SMS como alternativa”. No entanto, o comando a seguir foi imediatamente WhatsApp -> SMS como alternativa.

Send a personalized holiday greeting for my
friends in the holiday_contracts.csv. RCS and
WhatsApp are preferred over SMS but if RCS or
WhatsApp don't work you can failover to SMS.
Use the preferences you find in the csv

Talvez adicionar uma coluna que classificasse as preferências de comunicação do usuário tivesse dado ao agente contexto suficiente para fazer isso corretamente. Experimente e conte para a gente no nosso Slack da Comunidade!

Conclusão

Você teve algum problema ao configurar seu agente? Talvez você queira criar um chatbot dedicado, com todas as funcionalidades de um aplicativo, para funcionar fora do seu IDE? Se for o caso, confira Adicionando APIs da Vonage ao seu agente de IA. Esse chatbot foi a inspiração para este post! Tudo o que precisei fazer foi adicionar as ferramentas desejadas ao nosso servidor MCP.

Quer ver mais ferramentas no servidor? É código aberto! Então, construa o futuro que você deseja. Vou dar mais detalhes em um próximo post no blog, mas, basicamente... adoraríamos receber algumas solicitações de pull!