Migrar da Twilio para a volai numa tarde.

O que corresponde a quê

O SDK da Twilio não passa a apontar para a volai só por mudar um endereço - é uma API mais pequena e diferente. Os conceitos, porém, correspondem um a um.

Código lado a lado

Enviar um SMS - a mesma ideia, uma API diferente.

const twilio = require("twilio");
const client = twilio(accountSid, authToken);

await client.messages.create({
  body: "Hi from Twilio!",
  from: "+15017122661",
  to: "+420777123456",
});

await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Hi from volai!",
  }),
});

A Twilio define o remetente com o campo from. A volai ignora from e escolhe o remetente com fromNumber (um número de GET /v1/sms-numbers, o complemento número de telemóvel, ou de GET /v1/voice-sms-numbers, o número para chamadas e SMS). Sem fromNumber, os SMS saem com o nome de remetente partilhado SMSinfo, ao qual os destinatários não podem responder.

Entregue-o ao seu agente de IA

Copie o prompt para o Claude Code, o Cursor ou outro editor de IA e deixe que seja ele a fazer a migração - o SKILL.md dá-lhe a referência completa.

Lê o SKILL.md do site da volai (o URL base da API consta aí). Encontra no meu projeto as chamadas ao SDK da Twilio para SMS e chamadas (client.messages.create, client.calls.create) e reescreve-as para a API REST da volai: POST /v1/messages para SMS, POST /v1/calls para chamadas, cabeçalho Authorization: Bearer vk_YOUR_KEY. Atualiza também a receção de webhooks para o formato do SKILL.md, incluindo a verificação do cabeçalho Volai-Signature.

Lista de verificação da mudança

1. 1

   Número

   Compre um número checo (POST /v1/numbers ou no portal) e defina o seu encaminhamento - agente, reencaminhamento ou SIP. Para receber SMS e enviar a partir do seu próprio número, compre também um número de telemóvel (POST /v1/sms-numbers ou no portal, em Números): um número móvel checo só para SMS, sem chamadas. Se quer chamadas e SMS no mesmo número, encomende um número para chamadas e SMS em vez dos dois números (POST /v1/voice-sms-numbers ou no portal): um número fixo de Praga que é registado junto do operador depois de o encomendar, normalmente em 1 dia útil. As chamadas nele são atendidas apenas por um agente no motor de voz próprio da volai (não pode ser encaminhado para SIP nem reencaminhado), pelo que não serve para um agente que funcione noutro local.

2. 2

   Chave

   Gere uma chave de API no portal, em Assistente de IA.

3. 3

   Webhook

   Defina o webhook (PUT /v1/webhook) para o mesmo endereço que o seu StatusCallback da Twilio usa hoje e atualize o handler para o novo formato de evento. Se o endereço contiver nome de utilizador e palavra-passe, mova o login para um cabeçalho personalizado (headers, por exemplo Authorization: Basic ...); a volai rejeita um endereço com credenciais.

4. 4

   Teste

   Antes de passar o tráfego real, envie um SMS a si próprio e faça uma chamada de teste para o seu telemóvel.

5. 5

   DNS e contactos antigos

   Normalmente não precisa de mexer no DNS - a volai não usa o seu domínio. Verifique, isso sim, sites, assinaturas de e-mail e documentação onde o número antigo esteja escrito à mão.

Quando ficar com a Twilio

Migrar não é para todos - além da visão geral acima, pondere também o seguinte:

• As chamadas efetuadas a partir da volai só chegam a números checos e eslovacos (+420, +421) - não pode ligar para o estrangeiro, nem sequer a partir de um número checo que lhe pertença.
• Precisa de mais de 60 pedidos por minuto - é o limite de taxa partilhado tanto pela API REST como pelo servidor MCP.