ThunderPhone v3 já está no ar.Contrate online, a partir de 2¢/min.Leia o anúncio

Developer cookbook

Faça chamadas pelo Slack ou por um aplicativo de chat

Crie seu próprio bot para Slack, Teams ou chat na web que inicia chamadas, as acompanha ao vivo, orienta o agente e responde às suas perguntas usando a API pública.

Você pode controlar um agente pelo app de chat que sua equipe já usa. Uma mensagem inicia uma chamada. A chamada acontece ao vivo em uma thread. Uma resposta na thread orienta o agente. Quando o agente precisa de uma decisão, ele pergunta ali e aguarda sua resposta.

O ThunderPhone não hospeda esse bot para você. Você (ou seu agente de programação) cria um pequeno servidor que conecta seu app de chat à API pública. Esta página mostra os componentes. Eles são os mesmos para Slack, Microsoft Teams, Discord ou uma página privada de chat na web; os exemplos usam o Slack.

Como tudo se encaixa

Você faz isto no chatSeu bot chamaO que acontece
Envie "Ligue para a Comcast e descubra a previsão de retorno do serviço"POST /v1/call com a mensagem como contextO agente liga. Seu bot abre uma thread para a chamada
Acompanhe a threadRecebe webhooks telephony.turnCada fala do agente ou da outra pessoa aparece na thread
Responda na thread durante a chamadaPOST /v1/calls/{call_id}/whisperO agente recebe sua observação em particular e age de acordo. A outra pessoa nunca a ouve
Responda à pergunta do agenteSeu endpoint de ferramenta retorna sua resposta ou a entrega depois com POST /v1/calls/{call_id}/tool-resultsO agente continua a chamada com ela; no modo de espera, a outra pessoa ouve música de espera enquanto isso
Leia o resultadoRecebe telephony.completeSeu bot publica o resumo e o resultado

Seu bot mantém um mapeamento: qual thread de chat pertence a qual call_id.

Antes de começar

  • Uma chave de API, mantida no seu servidor e nunca em um navegador ou chat. Crie uma em Integrações → Chaves de API (consulte Criar uma chave de API de servidor).
  • Um número habilitado para chamadas de saída e um agente para as chamadas. A mensagem se torna o context de cada chamada, portanto um agente geral lida com todas as tarefas.
  • Um servidor que possa receber webhooks, como Railway, Fly.io, Render ou seu próprio host.
  • Um endpoint de webhook apontando para esse servidor e inscrito em telephony.turn e telephony.complete. Os eventos de turno são enviados apenas para endpoints que os listam. Consulte Webhooks. Os eventos de turno exigem que a gravação de chamadas do agente esteja ativada, e o summary do fim da chamada exige a configuração Gerar um resumo da chamada do agente; sem elas, esses campos permanecem vazios.
  • Seu próprio aplicativo de chat. Para o Slack, crie um aplicativo no seu workspace em api.slack.com/apps.

1. Inicie uma chamada a partir de uma mensagem

Quando seu bot receber uma mensagem (uma mensagem direta ou uma @menção), confirme a solicitação do Slack imediatamente (o Slack tenta novamente tudo o que não for confirmado em até 3 segundos) e faça o restante em segundo plano. Verifique se quem enviou a mensagem tem permissão para realizar chamadas e inicie a chamada com a mensagem como context:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'

Salve o call_id retornado na thread do Slack (channel mais o ts da mensagem) e responda na thread ("Ligando…"). Crie a idempotency_key a partir do canal e do ts da mensagem (um ts é exclusivo apenas dentro de seu canal), para que um evento do Slack repetido não realize uma segunda chamada. Se a solicitação informar o nome de uma pessoa em vez de um número, seu bot primeiro procura o número. O ThunderPhone disca somente o to_number que você enviar.

2. Acompanhe a chamada na thread

Cada webhook telephony.turn inclui o call_id, quem está falando (role: assistant para o agente, user para a outra pessoa), o text e a position do turno. Localize a thread pelo call_id e publique a linha.

  • Verifique cada webhook antes de agir com base nele. Consulte Verificar assinaturas de webhooks.
  • Elimine duplicatas usando o event_id do envelope e ordene por position. A entrega ocorre pelo menos uma vez, e os turnos podem chegar fora de ordem.
  • Agrupe linhas se uma chamada movimentada puder sobrecarregar a thread; publicar a cada poucos segundos é mais fácil de ler do que uma mensagem por linha.

Quando telephony.complete chegar, publique como a chamada terminou (seus status e end_reason), o summary e quaisquer dados extraídos, e encerre a thread. Consulte Conclusão da chamada para ver os campos.

3. Direcione a chamada pela thread

Quando alguém responder na thread de uma chamada ativa, envie a resposta como um sussurro, a menos que o agente esteja aguardando uma pergunta (etapa 4); nesse caso, a resposta será a resposta à pergunta:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'

O agente ouve isso em particular e o incorpora ao próximo turno; a outra pessoa nunca ouve o sussurro em si. Um sussurro tem de 1 a 1000 caracteres. Um 409 significa que a chamada não está mais ativa: informe à thread que a chamada terminou.

4. Deixe o agente perguntar a você

Dê ao agente uma ferramenta, por exemplo ask_owner, com um parâmetro question, que chama seu servidor. Crie-a como uma conexão de API e vincule-a ao agente. Cada solicitação de ferramenta inclui a chamada no cabeçalho X-ThunderPhone-Call-ID.

Há três formas de receber a resposta.

Mantenha a chamada em espera (até 10 minutos). Configure a ferramenta para o modo de espera: spec.wait_mode "hold" e spec.timeout de até 600 segundos (sem um tempo limite, a espera dura 20 segundos), pela API, ou peça ao Zeus para configurá-los (os editores do aplicativo ainda não têm nenhum dos dois campos). Seu endpoint publica a pergunta na thread da chamada e responde imediatamente com um resultado pendente:

{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}

A outra pessoa ouve uma frase do agente e, em seguida, música de espera. Em um menu telefônico ou caixa postal, o agente usa atualizações faladas, e um agente full-duplex não coloca em espera: ele recebe a resposta pendente como resultado. Quando a resposta chega no tópico, entregue-a com POST /v1/calls/{call_id}/tool-results:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'

A música diminui e o agente continua com sua resposta. Se ninguém responder antes do timeout, o agente é informado de que não houve resposta e oferece os próximos passos à outra pessoa. Enquanto uma pergunta estiver pendente em uma chamada, a próxima resposta no tópico a responderá: entregue-a como resultado da ferramenta e não a envie também como um sussurro (um sussurro só chega ao agente após a ferramenta retornar). Consulte Esperas longas.

Aguarde na solicitação (até 3 minutos). Seu endpoint publica a pergunta, aguarda uma resposta e a retorna, como {"answer": "Yes, book Tuesday at 10."}. Defina o spec.timeout da ferramenta pela API, com até 180 segundos (o padrão é 20). Dê ao seu endpoint um prazo próprio alguns segundos menor (por exemplo, 170 segundos), para que, quando ninguém responder, ele ainda retorne algo com que o agente possa agir, como {"answer": null, "note": "No reply yet. Offer to take a message."}. Uma ferramenta que atinge seu timeout chega ao agente como um erro, e seu host deve manter uma solicitação aberta por todo esse tempo. Enquanto aguarda, o agente informa à outra pessoa que está verificando, diz que ainda está trabalhando após cerca de 12 segundos e depois dá uma breve atualização aproximadamente a cada 15 segundos. O modo de espera funciona aqui também: defina spec.wait_mode como "hold" e a outra pessoa ouvirá música em vez das atualizações.

Responda por sussurro. Seu endpoint publica a pergunta e retorna imediatamente, por exemplo {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Quando a resposta chegar, envie-a como um sussurro (etapa 3), e o agente responderá a ela imediatamente. Use isso para respostas que podem levar mais de 10 minutos. A chamada não é colocada em espera: seu prompt deve informar ao agente o que fazer enquanto isso, como fazer companhia à pessoa ou oferecer-se para ligar de volta.

Em todos os casos, diga no prompt do agente quando usar a ferramenta e o que dizer à outra pessoa enquanto aguarda:

When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.

Limites a considerar

  • Seu endpoint deve responder dentro do timeout da ferramenta, no máximo em 180 segundos. Uma ferramenta no modo de espera pode manter a chamada em espera por até 600 segundos com um resultado pendente.
  • Enquanto uma ferramenta aguarda, o agente não responde à outra pessoa. No modo de espera, ela ouve música; caso contrário, atualizações curtas faladas.
  • Um sussurro tem no máximo 1000 caracteres.
  • A entrega de telephony.turn ocorre pelo menos uma vez e pode chegar fora de ordem.

Checklist de segurança

  • Mantenha a chave de API no seu servidor.
  • Verifique as assinaturas do ThunderPhone em webhooks e solicitações de ferramentas, e o segredo de assinatura do Slack nas solicitações do Slack. As duas assinaturas do ThunderPhone usam segredos diferentes: as entregas de webhook usam o segredo do próprio endpoint de webhook, e as solicitações de ferramentas usam o segredo de webhook da sua organização em GET /v1/webhook.
  • Decida quem pode iniciar chamadas: verifique o ID de usuário do Slack antes de fazer uma.
  • As chamadas de saída seguem as mesmas regras de qualquer outra. Consulte Leis sobre chamadas de saída.

Crie com um agente de programação

Direcione seu agente de programação para o servidor MCP da documentação e para esta página, e peça "um bot do Slack para meu agente ThunderPhone que siga este guia". Zeus, o assistente no app ThunderPhone, pode configurar o lado do agente (o endpoint de webhook, a ferramenta e as linhas do prompt) e escrever o código inicial do bot no chat.