Open in
Conectar a partir do Twilio
Envie chamadas do Twilio para um agente ThunderPhone via SIP com o CallSid e retorne-as pelo seu referUrl com a transferência no endereço de transferência.
Seu TwiML disca o endereço SIP do agente com o CallSid da chamada em um cabeçalho.
Quando quem liga precisa falar com uma pessoa, o agente envia um REFER SIP, o Twilio passa o
endereço de transferência com os dados da transferência para o manipulador referUrl, e o
TwiML retornado pelo seu manipulador decide para onde quem liga vai, como uma fila do Flex.
Antes de começar
- Um agente ThunderPhone e uma chave de API da organização.
- Twilio Programmable Voice e algum lugar para disponibilizar TwiML e um manipulador
referUrl: seu próprio servidor ou um TwiML Bin e uma Twilio Function. O Flex é opcional.
1. Crie o endpoint SIP
O <Sip> do Twilio recebe um nome de usuário e uma senha, então use um endpoint padrão:
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"}'Guarde imediatamente a password da resposta; ela é exibida apenas uma vez. Para
aceitar chamadas somente do Twilio também, consulte
Restringir IPs de origem.
2. Envie chamadas com contexto
Retorne este TwiML para a chamada que você deseja encaminhar ao 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é importante: o Twilio usa UDP, a menos que seja instruído de outra forma.X-Call-IDtransporta oCallSid. O Twilio não documenta um cabeçalho call-id próprio, então adicione este: o ThunderPhone o armazena como oexternal_call_idda chamada.{{CallSid}}funciona em um TwiML Bin; no seu próprio servidor, use oCallSidda solicitação recebida.- Adicione mais contexto da mesma forma, como
&X-Account-Id=12345. Dentro do TwiML, escreva&como&, pois um&isolado é XML inválido. Cada um chega ao prompt como uma variável, neste caso{{sip_x_account_id}}. O Twilio permite cabeçalhosx-eUser-to-User, codificados em porcentagem, com toda a URI tendo menos de 255 caracteres e os cabeçalhos menos de 1.024. referUrlpermite que o Twilio aceite oREFERdo agente; sem ele, a transferência falha com o erro 13802.answerOnBridge="true"mantém quem liga conectado até que o novo destino atenda, para que uma transferência com falha possa recorrer a uma alternativa.
O widget Conectar chamada a do Studio não documenta cabeçalhos personalizados nem
referUrl, então, a partir do Studio, encaminhe a chamada para este TwiML, por exemplo
com um widget Redirecionamento de TwiML.
3. Receba a chamada de volta
O agente transfere com um REFER cujo endereço de transferência contém o ID e a intenção do repasse. Adicione este número de transferência (consulte
Adicionar o número de transferência
e Cabeçalhos no endereço de transferência):
{
"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
}O Twilio envia o endereço completo para seu referUrl como ReferTransferTarget, por
exemplo <sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>.
Seu manipulador extrai os cabeçalhos dele e retorna o TwiML para onde quem liga
vai em seguida. A parte de usuário do endereço (support) fica a seu critério, então você pode
adicionar um número de transferência por destino e fazer o roteamento com base nele.
Esta Function do Twilio enfileira quem liga no Flex com o repasse como atributos
da tarefa e busca o resumo pelo ID do repasse. A consulta é executada em uma
Function porque o widget HTTP Request do Studio não consegue enviar o cabeçalho
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);
};Mantenha a chave de API nas variáveis de ambiente da Function. Consulte Buscar uma chamada repassada para conhecer os outros campos.
Teste
Ligue para um número do Twilio que retorne o TwiML acima, peça ao agente para
falar com uma pessoa e verifique se seu manipulador referUrl recebe ReferTransferTarget com ambos
os cabeçalhos e se quem liga chega à fila. Em seguida, abra a chamada com
GET /v1/calls/{call_id}: external_call_id deve ser o CallSid.
Limites
- O Twilio limita
Refer-Toa 256 caracteres. O ThunderPhone mantém o endereço em 254 e omite um cabeçalho que não caiba, então mantenha nomes e valores dos cabeçalhos curtos. - O Twilio não documenta a leitura de cabeçalhos em um
BYE, portanto um retorno não pode levar o repasse de volta ao Twilio. Use umREFERconforme acima. - O Twilio não aceita um
REFERem uma chamada conectada por<Conference>ou<Queue>, então conecte o agente com<Dial><Sip>conforme acima.