--- title: "Usa ThunderPhone con n8n" description: "Instala el nodo de ThunderPhone para n8n, conecta una clave de API del servidor y crea un flujo de trabajo que se ejecute cada vez que termine una llamada." --- [n8n](https://n8n.io) es una herramienta de automatización de flujos de trabajo. El paquete de ThunderPhone para n8n agrega dos nodos: - **ThunderPhone Trigger** inicia un flujo de trabajo cuando termina una llamada (**Llamada completada**) o finaliza una ejecución de calificación de llamadas (**Llamada calificada**). - **ThunderPhone** realiza llamadas salientes, agrega contactos a campañas y las inicia, obtiene llamadas con su transcripción y grabación, y muestra tus agentes y números de teléfono. Es un nodo comunitario verificado, incluido en [ThunderPhone en n8n](https://n8n.io/integrations/thunderphone/). ## Instala el nodo En el editor de n8n, haz clic en **+** para abrir el panel de nodos y busca **ThunderPhone**. Es posible que el propietario de la instancia deba configurar nodos verificados antes de que otros usuarios puedan agregarlos. En n8n autoalojado, también puedes instalarlo por nombre de paquete: abre **Configuración > Nodos comunitarios** e instala `n8n-nodes-thunderphone`. Revisa los riesgos de los nodos comunitarios y la política de tu instancia antes de instalarlo. ## Crea una clave de API de servidor En ThunderPhone, ve a **Organización → Claves** y haz clic en **Crear clave**. Usa un nombre que indique dónde se encuentra la clave, como "n8n". El secreto completo `sk_live_...` se muestra una sola vez. Cópialo antes de cerrar el cuadro de diálogo. Solo un administrador o propietario puede crear la clave, y ThunderPhone trata las solicitudes realizadas con ella como si provinieran de esa persona. El trigger y las operaciones de campaña requieren que esa persona mantenga el rol de administrador o propietario. [Crear una clave de API de servidor](/es/guides/api-keys) incluye información sobre rotación y revocación. ## Agrega la credencial en n8n 1. En n8n, crea una credencial de tipo **ThunderPhone API**. 2. Pega la clave en **Clave de API**. 3. Guárdala y ejecuta la prueba de credencial. La prueba lee una llamada de tu organización con `GET /v1/calls?limit=1`. ## Crea un primer flujo de trabajo Este flujo de trabajo agrega una fila a una hoja de cálculo de Google cada vez que termina una llamada. Agrega **ThunderPhone Trigger**, selecciona tu credencial de API de ThunderPhone y establece **Evento** en **Llamada completada**. Agrega un nodo **ThunderPhone**. Establece **Recurso** en **Llamada**, **Operación** en **Obtener** e **ID de llamada** en la expresión `{{ $json.data.call_id }}`. La salida es el [registro de la llamada](/api-reference/calls) más `transcripts` y `recording_url`, un enlace de corta duración que es `null` cuando la llamada no tiene grabación. Agrega un nodo de Google Sheets que añada una fila y asigna las columnas que quieras desde la salida de Obtener llamada (consulta la tabla a continuación). Guarda y activa. El desencadenante registra su URL de producción como un endpoint de webhook en tu organización de ThunderPhone. Desactivar el flujo de trabajo elimina ese endpoint. Abre un agente en el creador, haz clic en **Hablar** y termina la llamada. Las llamadas de prueba del creador se entregan como `web.complete`, uno de los dos eventos detrás de Llamada completada, por lo que el flujo de trabajo se ejecuta y aparece una fila. Columnas útiles: | Columna | Expresión | |---|---| | ID de llamada | `{{ $json.call_id }}` | | Dirección | `{{ $json.direction }}` | | Desde | `{{ $json.from_number }}` | | Hasta | `{{ $json.to_number }}` | | Inicio | `{{ $json.start_time }}` | | Duración (s) | `{{ $json.duration_seconds }}` | | Estado | `{{ $json.status }}` | | Motivo de finalización | `{{ $json.end_reason }}` | | Enlace de la llamada | `https://app.thunderphone.com/dashboard/call-history/{{ $json.call_id }}` | El enlace de la llamada abre la llamada en el panel de ThunderPhone para los miembros de tu organización, con su transcripción y grabación, por lo que la hoja de cálculo no necesita almacenar ninguna de las dos. Para agregar la transcripción de todos modos, asigna `{{ $json.transcripts.filter(t => typeof t.content === 'string').map(t => t.role + ': ' + t.content).join('\n') }}`. La URL de la grabación vence, así que almacena el ID de llamada y ejecuta Obtener llamada de nuevo cuando necesites un enlace actualizado. Las transcripciones, los resúmenes y las grabaciones de llamadas pueden contener información personal o de salud. Envíalos solo a aplicaciones que tu organización esté autorizada a usar para esos datos, bajo un BAA cuando se trate de información de salud, y conserva únicamente los campos que necesites. ThunderPhone entrega eventos mediante `POST` a la **URL de producción** del desencadenante, por lo que tu instancia de n8n debe ser accesible mediante HTTPS desde internet y el flujo de trabajo debe estar activo. El desencadenante verifica el HMAC `X-ThunderPhone-Signature` en cada solicitud y responde `401` a cualquier solicitud sin firma o no válida. El desencadenante genera el evento completo: `type`, `event_id` y `data`. Consulta [`telephony.complete` / `web.complete`](/es/webhooks/call-complete) y [`call.graded`](/es/webhooks/events) para ver todos los campos. La entrega es al menos una vez, y `event_id` se mantiene igual en los reintentos de un mismo evento, así que verifícalo antes de un paso que no deba repetirse. ## Realiza llamadas salientes de forma segura **Realizar llamada saliente** (Recurso **Llamada saliente**, Operación **Realizar**) acepta: | Campo | Significado | |---|---| | Nombre o ID del agente | Un agente guardado. El menú desplegable muestra tus agentes. | | Nombre o ID del número de teléfono | El número de origen. El menú desplegable muestra solo los números habilitados para llamadas salientes. | | Número de destino | Destino en formato E.164, por ejemplo, `+14155552671`. | | Variables | Objeto JSON de valores para los marcadores de posición en el prompt del agente. | | Clave de idempotencia | Un ID estable del registro o evento ascendente. Obligatorio. | Asigna la **Clave de idempotencia** a un ID de lo que haya provocado la ejecución, como un ID de registro de CRM o el `event_id` del desencadenante. El nodo envía `n8n::`, por lo que: - Un reintento automático o **Reintentar ejecución** envía la misma clave, y ThunderPhone devuelve la llamada original con `idempotent_replay: true` en lugar de marcar de nuevo. - Dos nodos de ThunderPhone alimentados con el mismo registro envían claves diferentes. - Un valor vacío falla antes de que se envíe cualquier solicitud. Evita las marcas de tiempo, los valores aleatorios y los ID de ejecución o flujo de trabajo de n8n. Un valor nuevo durante un reintento realiza una segunda llamada real. La clave completa puede tener como máximo 128 caracteres. Reutilizar una clave con un agente, número o variables diferentes falla por conflicto. **Campañas.** **Agregar contactos** (Recurso **Campaña**) agrega contactos a una campaña en borrador. Acepta un ID de campaña y una matriz JSON de contactos. Cada contacto necesita `phone_number`; las demás claves se convierten en variables de llamada. El nodo falla cuando todos los contactos se rechazan y establece `partial_success: true` cuando solo se rechazan algunos. **Iniciar** requiere la casilla de verificación que confirma que la campaña realiza llamadas reales y consume créditos de ThunderPhone. Consulta [Campañas salientes](/es/guides/outbound-campaigns). Antes de que un flujo de trabajo inicie llamadas: - Si ThunderPhone solicita a tu organización confirmar que sus llamadas salientes cumplen con la TCPA y otras leyes de llamadas, un administrador debe registrar primero esa confirmación en el dashboard. - El número de origen debe estar habilitado para llamadas salientes. Los números que traigas de tu propio operador califican una vez verificados. Los números de ThunderPhone comienzan solo para llamadas entrantes y pueden aprobarse para uso saliente: un administrador lo solicita desde la página Números de teléfono. Consulta [Obtener un número de teléfono](/es/guides/get-a-phone-number). - Tu organización es responsable de contar con el consentimiento para llamar a cada número y de cumplir con las leyes de llamadas aplicables. Consulta [Leyes sobre llamadas salientes](/es/guides/outbound-calling-laws). ## Flujos de trabajo de ejemplo - **Contactos de CRM a una campaña.** Agrega contactos de CRM a una campaña de ThunderPhone en borrador y luego inicia la campaña cuando alguien apruebe la lista. - **Llamada completada al registro del cliente.** En Llamada completada, ejecuta Obtener llamada y guarda la transcripción y el enlace de la grabación en el registro de cliente correspondiente. - **Calificaciones bajas para revisión.** En Llamada calificada, filtra por `{{ $json.data.grade.score }}` y dirige las llamadas con puntuaciones bajas a una cola de revisión con el ID de llamada y los detalles de la calificación. Una llamada puede calificarse más de una vez, y cada ejecución de calificación finalizada activa el desencadenante, así que conserva solo el último `graded_at` para cada ID de llamada. Las transcripciones, los resúmenes y las grabaciones de llamadas pueden contener información personal o de salud. Envíalos solo a aplicaciones que tu organización esté autorizada a usar para esos datos, con un BAA cuando haya información de salud involucrada, y conserva únicamente los campos que necesites. ¿Envías los mismos eventos de llamadas a tu propio servidor? Consulta [Puntos de conexión de webhook](/es/webhooks/endpoints). [Realizar llamadas salientes](/es/guides/place-outbound-calls) explica la API detrás de Realizar llamada saliente.