ThunderPhone v3 já está no ar.Contrate online, a partir de 2¢/min.Leia o anúncio

Contact centers

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-ID transporta o CallSid. O Twilio não documenta um cabeçalho call-id próprio, então adicione este: o ThunderPhone o armazena como o external_call_id da chamada. {{CallSid}} funciona em um TwiML Bin; no seu próprio servidor, use o CallSid da solicitação recebida.
  • Adicione mais contexto da mesma forma, como &amp;X-Account-Id=12345. Dentro do TwiML, escreva & como &amp;, 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çalhos x- e User-to-User, codificados em porcentagem, com toda a URI tendo menos de 255 caracteres e os cabeçalhos menos de 1.024.
  • referUrl permite que o Twilio aceite o REFER do 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-To a 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 um REFER conforme acima.
  • O Twilio não aceita um REFER em uma chamada conectada por <Conference> ou <Queue>, então conecte o agente com <Dial><Sip> conforme acima.