---
title: "Conéctate desde Twilio"
description: "Envía llamadas de Twilio a un agente de ThunderPhone mediante SIP con el CallSid y recupéralas a través de tu referUrl con la transferencia en la dirección de transferencia."
---

Tu TwiML marca la dirección SIP del agente con el `CallSid` de la llamada en un encabezado.
Cuando quien llama necesita una persona, el agente envía un `REFER` SIP, Twilio pasa la
dirección de transferencia con el traspaso dentro a tu controlador `referUrl`, y el
TwiML que devuelve tu controlador decide adónde va quien llama, como una cola de Flex.

## Antes de comenzar

- Un agente de ThunderPhone y una [clave de API](/es/guides/api-keys) de la organización.
- Twilio Programmable Voice y algún lugar donde servir TwiML y un controlador
  `referUrl`: tu propio servidor, o un TwiML Bin y una Twilio Function. Flex es
  opcional.

## 1. Crea el endpoint SIP

El `<Sip>` de Twilio requiere un nombre de usuario y una contraseña, así que usa un endpoint estándar:

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12, "name": "Twilio"}'
```

Guarda de inmediato el `password` de la respuesta; se muestra una sola vez. Para
aceptar llamadas también solo desde Twilio, consulta
[Restringir IP de origen](/es/guides/sip-addresses).

## 2. Envía llamadas con contexto

Devuelve este TwiML para la llamada que quieras entregar al agente:

```xml
<Response>
  <Dial answerOnBridge="true" referUrl="https://YOUR_SERVER/thunderphone-refer">
    <Sip username="tp409667538f83" password="YOUR_ENDPOINT_PASSWORD">sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tls?X-Call-ID={{CallSid}}</Sip>
  </Dial>
</Response>
```

- `;transport=tls` es importante: Twilio usa UDP a menos que indiques lo contrario.
- `X-Call-ID` lleva el `CallSid`. Twilio no documenta un encabezado de ID de llamada
  propio, así que agrega este: ThunderPhone lo almacena como el
  `external_call_id` de la llamada. `{{CallSid}}` funciona en un TwiML Bin; desde tu
  propio servidor, escribe el `CallSid` de la solicitud entrante.
- Agrega más contexto de la misma forma, como `&amp;X-Account-Id=12345`. Dentro de
  TwiML, escribe `&` como `&amp;`, ya que un `&` sin escapar no es XML válido. Cada
  uno llega al prompt como una variable, aquí `{{sip_x_account_id}}`. Twilio permite
  encabezados `x-` y `User-to-User`, codificados en porcentaje, con la URI completa
  de menos de 255 caracteres y los encabezados de menos de 1,024.
- `referUrl` permite que Twilio acepte el `REFER` del agente; sin él, la transferencia
  falla con el [error 13802](https://www.twilio.com/docs/api/errors/13802).
  `answerOnBridge="true"` mantiene conectado a quien llama hasta que responda el nuevo destino,
  para que una transferencia fallida pueda tener una alternativa.

El widget **Conectar llamada a** de Studio no documenta encabezados personalizados ni
`referUrl`, así que desde Studio entrega la llamada a este TwiML, por ejemplo con un
widget de **Redirección de TwiML**.

## 3. Recibe la llamada de vuelta

El agente transfiere con un `REFER` cuya dirección de transferencia contiene el
id y la intención del traspaso. Agrega este número de transferencia (consulta
[Agregar el número de transferencia](/es/guides/contact-centers/overview)
y [Encabezados dentro de la dirección de transferencia](/es/guides/call-transfers)):

```json
{
  "name": "Twilio support",
  "number": "sip:support@acme.sip.twilio.com",
  "headers": {"X-Handoff-Id": "{{handoff_id}}", "X-Handoff-Intent": "{{handoff_intent}}"},
  "headers_in_uri": true
}
```

Twilio envía la dirección completa a tu `referUrl` como `ReferTransferTarget`, por
ejemplo `<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>`.
Tu controlador extrae los encabezados y devuelve TwiML para indicar adónde va
después la persona que llama. La parte de usuario de la dirección (`support`) la
eliges tú, así que puedes agregar un número de transferencia por destino y
enrutar según él.

Esta Function de Twilio pone en cola a la persona que llama en Flex con el
traspaso como atributos de tarea y busca el resumen mediante el id de traspaso.
La búsqueda se ejecuta en una Function porque el widget de solicitud HTTP de
Studio no puede enviar el encabezado `Authorization`:

```js
exports.handler = async (context, event, callback) => {
  const target = (event.ReferTransferTarget || "").replace(/^<|>$/g, "");
  const params = new URLSearchParams(target.split("?")[1] || "");
  const handoffId = params.get("X-Handoff-Id") || "";
  const attributes = { handoff_id: handoffId, intent: params.get("X-Handoff-Intent") || "" };

  if (handoffId) {
    const response = await fetch(
      "https://api.thunderphone.com/v1/calls/handoff?handoff_id=" + encodeURIComponent(handoffId),
      { headers: { Authorization: "Bearer " + context.THUNDERPHONE_API_KEY } }
    );
    if (response.ok) {
      const call = await response.json();
      attributes.summary = (call.handoff && call.handoff.summary) || "";
    }
  }

  const twiml = new Twilio.twiml.VoiceResponse();
  twiml.enqueue({ workflowSid: context.FLEX_WORKFLOW_SID }).task({}, JSON.stringify(attributes));
  callback(null, twiml);
};
```

Guarda la clave de API en las variables de entorno de la Function. Consulta
[Buscar una llamada transferida](/api-reference/calls#look-up-a-handed-off-call)
para conocer los demás campos.

## Pruébalo

Llama a un número de Twilio que devuelva el TwiML anterior, pídele al agente que
te transfiera a una persona y verifica que tu controlador `referUrl` reciba
`ReferTransferTarget` con ambos encabezados y que la persona que llama llegue a
la cola. Luego abre la llamada con `GET /v1/calls/{call_id}`: `external_call_id`
debe ser el `CallSid`.

## Límites

- Twilio limita `Refer-To` a 256 caracteres. ThunderPhone mantiene la dirección
  en 254 y omite cualquier encabezado que no quepa, así que mantén cortos los
  nombres y valores de los encabezados.
- Twilio no documenta la lectura de encabezados en un `BYE`, así que un retorno
  no puede llevar el traspaso de vuelta a Twilio. Usa un `REFER` como se indicó
  arriba.
- Twilio no acepta un `REFER` en una llamada conectada mediante `<Conference>` o
  `<Queue>`, así que marca al agente con `<Dial><Sip>` como se indicó arriba.
