Open in
Realiza llamadas desde Slack o una app de chat
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 con el mensaje como context | El agente marca. Tu bot abre un hilo para la llamada |
| Observa el hilo | Recibe webhooks de telephony.turn | 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 | 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 devuelve tu respuesta o la entrega más tarde con POST /v1/calls/{call_id}/tool-results | 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 | 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).
- Un número habilitado para llamadas salientes y un agente para las llamadas. El mensaje
se convierte en
contextpor 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.turnytelephony.complete. Los eventos de turno solo se envían a endpoints que los incluyen. Consulta Webhooks. Los eventos de turno requieren que la grabación de llamadas del agente esté activada, y elsummaryal 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.
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:
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.
- Deduplica por el
event_iddel sobre y ordena porposition. 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 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:
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 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, 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:
{"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:
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.
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:
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
timeoutde 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.turnocurre 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. - 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.
Créalo con un agente de programación
Dirige tu agente de programación al servidor MCP de la documentación 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.