---
title: "Realiza llamadas desde Slack o una app de chat"
description: "Crea tu propio bot para Slack, Teams o chat web que inicie llamadas, las siga en vivo, guíe al agente y responda sus preguntas mediante la API pública."
---

Puedes controlar un agente desde la aplicación de chat que tu equipo ya usa. Un mensaje
inicia una llamada. La llamada se desarrolla en vivo en un hilo. Una respuesta en el hilo
orienta al agente. Cuando el agente necesita una decisión, te pregunta allí y
espera tu respuesta.

ThunderPhone no aloja este bot por ti. Tú (o tu agente de programación) creas un
servidor pequeño que conecta tu aplicación de chat con la API pública. Esta página muestra
las piezas. Son las mismas para Slack, Microsoft Teams, Discord o una página de chat web
privada; los ejemplos usan Slack.

## Cómo funciona en conjunto

| Lo que haces en el chat | Lo que llama tu bot | Qué sucede |
|---|---|---|
| Envía "Llama a Comcast y obtén la hora estimada de restablecimiento" | [`POST /v1/call`](/api-reference/outbound-calls) con el mensaje como `context` | El agente marca. Tu bot abre un hilo para la llamada |
| Observa el hilo | Recibe webhooks de [`telephony.turn`](/es/webhooks/events) | Cada línea que dice el agente o la otra persona aparece en el hilo |
| Responde en el hilo durante la llamada | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | El agente recibe tu nota de forma privada y actúa según ella. La otra persona nunca la escucha |
| Responde la pregunta del agente | Tu [endpoint de herramienta](/es/guides/build-tool-integration) devuelve tu respuesta o la entrega más tarde con [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | El agente continúa la llamada con ella; en modo de espera, la otra persona escucha música de espera mientras tanto |
| Lee el resultado | Recibe [`telephony.complete`](/es/webhooks/events) | Tu bot publica el resumen y el resultado |

Tu bot mantiene una asignación: qué hilo de chat corresponde a cada `call_id`.

## Antes de comenzar

- **Una clave de API**, guardada en tu servidor y nunca en un navegador ni en un chat.
  Crea una en **Integraciones → Claves de API** (consulta
  [Crear una clave de API de servidor](/es/guides/api-keys)).
- **Un número habilitado para llamadas salientes y un agente** para las llamadas. El mensaje
  se convierte en `context` por llamada, por lo que un agente general gestiona cada tarea.
- **Un servidor** que pueda recibir webhooks, como Railway, Fly.io, Render o
  tu propio host.
- **Un endpoint de webhook** que apunte a ese servidor y esté suscrito a
  `telephony.turn` y `telephony.complete`. Los eventos de turno solo se envían a
  endpoints que los incluyen. Consulta [Webhooks](/es/webhooks/endpoints).
  Los eventos de turno requieren que la grabación de llamadas del agente esté activada, y el
  `summary` al final de la llamada requiere la configuración **Generar un resumen de la llamada** del agente; sin
  ellas, esos campos permanecen vacíos.
- **Tu propia aplicación de chat.** Para Slack, crea una aplicación en tu espacio de trabajo en
  [api.slack.com/apps](https://api.slack.com/apps).

<Tip>
  Usa una aplicación de Slack que crees para tu propio espacio de trabajo y recibe mensajes
  mediante la API de eventos de Slack en lugar de leer el historial del canal. Slack
  impone límites de lectura estrictos a las aplicaciones distribuidas en otros espacios de trabajo fuera de
  su Marketplace; una aplicación que creas para tu propio espacio de trabajo no está sujeta a
  ellos, y los eventos te llegan a medida que ocurren sin ninguna lectura. Permisos
  típicos del bot: `chat:write`, `app_mentions:read`, `im:history` (mensajes
  directos), `channels:history` y `groups:history` (respuestas en hilos de
  canales públicos y privados en los que está el bot). Suscríbete a los eventos del bot
  `app_mention`, `message.im`, `message.channels` y `message.groups`, y
  activa la pestaña Mensajes en Inicio de la aplicación para que las personas puedan enviar mensajes directos al bot.
</Tip>

## 1. Inicia una llamada desde un mensaje

Cuando tu bot recibe un mensaje (un mensaje directo o una mención con @),
confirma la solicitud de Slack de inmediato (Slack vuelve a intentar cualquier cosa que no
se confirme en un plazo de 3 segundos) y realiza el resto en segundo plano. Verifica
que el remitente tenga permiso para realizar llamadas y, luego, inicia la llamada con el
mensaje 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"
  }'
```

Guarda el `call_id` devuelto asociado al hilo de Slack (`channel` más el
`ts` del mensaje) y responde en el hilo ("Llamando…"). Genera la
`idempotency_key` a partir del canal y el `ts` del mensaje (un `ts` es único
solo dentro de su canal), para que un evento de Slack reintentado no realice una segunda
llamada. Si la solicitud menciona a una persona en lugar de un número, tu bot
primero busca el número. ThunderPhone marca únicamente el `to_number` que envías.

## 2. Sigue la llamada en el hilo

Cada webhook `telephony.turn` incluye el `call_id`, el hablante (`role`:
`assistant` para el agente, `user` para la otra persona), el `text` y la
`position` del turno. Busca el hilo por `call_id` y
publica la línea.

- **Verifica cada webhook** antes de actuar sobre él. Consulta
  [Verificar firmas de webhooks](/es/guides/verify-webhook-signatures).
- **Deduplica por el `event_id` del sobre y ordena por `position`.**
  La entrega ocurre al menos una vez y los turnos pueden llegar desordenados.
- **Agrupa las líneas** si una llamada ocupada saturaría el hilo; publicar cada pocos
  segundos se lee mejor que un mensaje por línea.

Cuando llegue `telephony.complete`, publica cómo terminó la llamada (su `status`
y `end_reason`), el `summary` y cualquier dato extraído, y marca el
hilo como cerrado. Consulta [Llamada completada](/es/webhooks/call-complete) para conocer los campos.

## 3. Guía la llamada desde el hilo

Cuando alguien responde en el hilo de una llamada activa, envía la respuesta como un susurro,
a menos que el agente esté esperando una respuesta a una pregunta (paso 4), en cuyo caso la respuesta
es la contestación:

```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."}'
```

El agente lo escucha de forma privada y lo incorpora en su siguiente turno; la otra
persona nunca escucha el susurro en sí. Un susurro tiene de 1 a 1000 caracteres. Un
`409` significa que la llamada ya no está activa: indica en el hilo que la llamada terminó.

## 4. Deja que el agente te pregunte

Dale al agente una herramienta, por ejemplo `ask_owner` con un parámetro
`question`, que llame a tu servidor. Créala como una
[conexión de API](/es/guides/build-tool-integration) y vincúlala al agente.
Cada solicitud de herramienta incluye la llamada en su encabezado `X-ThunderPhone-Call-ID`.

Hay tres formas de recibir la respuesta.

**Mantén la llamada en espera (hasta 10 minutos).** Configura la herramienta en modo de espera: `spec.wait_mode`
`"hold"` y `spec.timeout` hasta 600 segundos (sin un tiempo de espera, la espera
dura 20 segundos), mediante la
[API](/api-reference/integrations#timeout-and-wait-mode), o pídele a Zeus que
los configure (los editores de la aplicación todavía no tienen ninguno de los dos campos). Tu endpoint publica la pregunta en el hilo de la llamada y responde de
inmediato con un resultado pendiente:

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

La otra persona escucha una línea del agente y luego música de espera. En un
menú telefónico o buzón de voz, el agente usa actualizaciones habladas en su lugar, y un
agente de dúplex completo no pone la llamada en espera: recibe la respuesta pendiente como resultado. Cuando la
respuesta llega al hilo, envíala con
[`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."}}'
```

La música se desvanece y el agente continúa con tu respuesta. Si nadie
responde antes del `timeout`, se le indica al agente que no llegó ninguna respuesta y le ofrece a
la otra persona los siguientes pasos. Mientras haya una pregunta pendiente para una llamada, la
siguiente respuesta en su hilo la responde: entrégala como resultado de la herramienta y
no la envíes también como susurro (un susurro solo llega al agente después de que
la herramienta devuelve un resultado). Consulta
[Esperas largas](/es/tools/overview).

**Espera en la solicitud (hasta 3 minutos).** Tu endpoint publica la pregunta,
espera una respuesta y la devuelve, como `{"answer": "Yes, book Tuesday at 10."}`.
Configura el `spec.timeout` de la herramienta mediante la API, hasta 180 segundos (el
valor predeterminado es 20). Dale a tu endpoint su propio plazo límite unos segundos más corto
(por ejemplo, 170 segundos), para que cuando nadie responda todavía devuelva
algo con lo que el agente pueda actuar, como
`{"answer": null, "note": "No reply yet. Offer to take a message."}`. Una herramienta
que alcanza su `timeout` llega al agente como un error, y tu host debe
mantener una solicitud abierta durante ese tiempo. Mientras espera, el agente le dice a
la otra persona que está verificando, indica que sigue trabajando después de unos 12 segundos y
luego ofrece una breve actualización aproximadamente cada 15 segundos. El modo de espera funciona
también aquí: configura `spec.wait_mode` en `"hold"` y la otra persona escucha música
en lugar de las actualizaciones.

**Responde mediante susurro.** Tu endpoint publica la pregunta y devuelve una respuesta de inmediato,
por ejemplo `{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}`.
Cuando llegue la respuesta, envíala como un susurro (paso 3), y el agente
responderá de inmediato. Usa esto para respuestas que puedan tardar más de
10 minutos. La llamada no queda en espera: tu prompt debe indicarle al
agente qué hacer mientras tanto, como hacerle compañía a la persona u ofrecer
volver a llamarla.

En todos los casos, indica en el prompt del agente cuándo usar la herramienta y qué decirle a
la otra persona mientras espera:

```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.
```

## Límites que debes considerar

- Tu endpoint debe responder dentro del `timeout` de la herramienta, como máximo en **180 segundos**. Una herramienta en modo de espera puede
  mantener la llamada en espera hasta **600 segundos** con un resultado pendiente.
- Mientras una herramienta espera, el agente no responde a la otra persona. En modo de espera,
  escucha música; de lo contrario, recibe breves actualizaciones habladas.
- Un susurro tiene un máximo de **1000 caracteres**.
- La entrega de `telephony.turn` ocurre al menos una vez y puede llegar fuera de orden.

## Lista de verificación de seguridad

- Mantén la clave de API en tu servidor.
- Verifica las firmas de ThunderPhone en los webhooks y las solicitudes de herramientas, y
  el secreto de firma de Slack en las solicitudes de Slack. Las dos firmas de ThunderPhone
  usan secretos diferentes: las entregas de webhooks usan el secreto propio del
  endpoint de webhook, y las solicitudes de herramientas usan el secreto de webhook de tu organización
  de [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook).
- Decide quién puede iniciar llamadas: verifica el ID de usuario de Slack antes de realizar una.
- Las llamadas salientes siguen las mismas reglas que cualquier otra. Consulta
  [Leyes sobre llamadas salientes](/es/guides/outbound-calling-laws).

## Créalo con un agente de programación

Dirige tu agente de programación al [servidor MCP de la documentación](/es/guides/docs-mcp) y a
esta página, y pídele "un bot de Slack para mi agente de ThunderPhone que siga
esta guía". Zeus, el asistente de la app de ThunderPhone, puede configurar la
parte del agente (el endpoint de webhook, la herramienta y las líneas del prompt) y escribir
código inicial para el bot en el chat.
