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

Contact centers

Conéctate desde Twilio

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 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:

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.

2. Envía llamadas con contexto

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

<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. 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 y Encabezados dentro de la dirección de transferencia):

{
  "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:

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