Open in
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=tlses importante: Twilio usa UDP a menos que indiques lo contrario.X-Call-IDlleva elCallSid. Twilio no documenta un encabezado de ID de llamada propio, así que agrega este: ThunderPhone lo almacena como elexternal_call_idde la llamada.{{CallSid}}funciona en un TwiML Bin; desde tu propio servidor, escribe elCallSidde la solicitud entrante.- Agrega más contexto de la misma forma, como
&X-Account-Id=12345. Dentro de TwiML, escribe&como&, 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 encabezadosx-yUser-to-User, codificados en porcentaje, con la URI completa de menos de 255 caracteres y los encabezados de menos de 1,024. referUrlpermite que Twilio acepte elREFERdel 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-Toa 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 unREFERcomo se indicó arriba. - Twilio no acepta un
REFERen una llamada conectada mediante<Conference>o<Queue>, así que marca al agente con<Dial><Sip>como se indicó arriba.