Open in
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 chat | Seu bot chama | O que acontece |
|---|---|---|
| Envie "Ligue para a Comcast e descubra a previsão de retorno do serviço" | POST /v1/call com a mensagem como context | O agente liga. Seu bot abre uma thread para a chamada |
| Acompanhe a thread | Recebe webhooks telephony.turn | Cada fala do agente ou da outra pessoa aparece na thread |
| Responda na thread durante a chamada | POST /v1/calls/{call_id}/whisper | O agente recebe sua observação em particular e age de acordo. A outra pessoa nunca a ouve |
| Responda à pergunta do agente | Seu endpoint de ferramenta retorna sua resposta ou a entrega depois com POST /v1/calls/{call_id}/tool-results | O agente continua a chamada com ela; no modo de espera, a outra pessoa ouve música de espera enquanto isso |
| Leia o resultado | Recebe telephony.complete | Seu 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
contextde 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.turnetelephony.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 osummarydo 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_iddo envelope e ordene porposition. 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
timeoutda 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.turnocorre 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.