---
title: "Faça chamadas pelo Slack ou por um aplicativo de chat"
description: "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`](/api-reference/outbound-calls) com a mensagem como `context` | O agente liga. Seu bot abre uma thread para a chamada |
| Acompanhe a thread | Recebe webhooks [`telephony.turn`](/pt/webhooks/events) | Cada fala do agente ou da outra pessoa aparece na thread |
| Responda na thread durante a chamada | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | 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](/pt/guides/build-tool-integration) retorna sua resposta ou a entrega depois com [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | 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`](/pt/webhooks/events) | 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](/pt/guides/api-keys)).
- **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](/pt/webhooks/endpoints).
  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](https://api.slack.com/apps).

<Tip>
  Use um app do Slack criado para seu próprio workspace e receba mensagens
  pela API de Eventos do Slack em vez de ler o histórico do canal. O Slack
  impõe limites rígidos de leitura a apps distribuídos para outros workspaces fora
  do Marketplace; um app criado para seu próprio workspace não está sujeito a
  eles, e os eventos chegam até você conforme acontecem, sem nenhuma leitura. Escopos
  típicos do bot: `chat:write`, `app_mentions:read`, `im:history` (mensagens
  diretas), `channels:history` e `groups:history` (respostas em threads de
  canais públicos e privados dos quais o bot participa). Inscreva-se nos eventos do bot
  `app_mention`, `message.im`, `message.channels` e `message.groups`, e
  ative a aba Mensagens em Página inicial do app para que as pessoas possam enviar mensagens diretas ao bot.
</Tip>

## 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`:

```bash
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](/pt/guides/verify-webhook-signatures).
- **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](/pt/webhooks/call-complete) 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:

```bash
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](/pt/guides/build-tool-integration) 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](/api-reference/integrations#timeout-and-wait-mode), 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:

```json
{"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`](/api-reference/calls#deliver-a-tool-result):

```bash
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](/pt/tools/overview).

**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:

```text
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`](/api-reference/organizations#legacy-single-url-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](/pt/guides/outbound-calling-laws).

## Crie com um agente de programação

Direcione seu agente de programação para o [servidor MCP da documentação](/pt/guides/docs-mcp) 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.
