ThunderPhone v3 ya está disponible.Empieza por tu cuenta desde 2¢/min.Lee el anuncio

Developer cookbook

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 chatLo que llama tu botQué sucede
Envía "Llama a Comcast y obtén la hora estimada de restablecimiento"POST /v1/call con el mensaje como contextEl agente marca. Tu bot abre un hilo para la llamada
Observa el hiloRecibe webhooks de telephony.turnCada línea que dice el agente o la otra persona aparece en el hilo
Responde en el hilo durante la llamadaPOST /v1/calls/{call_id}/whisperEl agente recibe tu nota de forma privada y actúa según ella. La otra persona nunca la escucha
Responde la pregunta del agenteTu endpoint de herramienta devuelve tu respuesta o la entrega más tarde con POST /v1/calls/{call_id}/tool-resultsEl agente continúa la llamada con ella; en modo de espera, la otra persona escucha música de espera mientras tanto
Lee el resultadoRecibe telephony.completeTu 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 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. 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.

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_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 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 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.
  • 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.