---
title: "Conectar a partir do Twilio"
description: "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](/pt/guides/api-keys) 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:

```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"}'
```

Guarde imediatamente a `password` da resposta; ela é exibida apenas uma vez. Para
aceitar chamadas somente do Twilio também, consulte
[Restringir IPs de origem](/pt/guides/sip-addresses).

## 2. Envie chamadas com contexto

Retorne este TwiML para a chamada que você deseja encaminhar ao 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` é 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](https://www.twilio.com/docs/api/errors/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](/pt/guides/contact-centers/overview)
e [Cabeçalhos no endereço de transferência](/pt/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
}
```

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

```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);
};
```

Mantenha a chave de API nas variáveis de ambiente da Function. Consulte
[Buscar uma chamada repassada](/api-reference/calls#look-up-a-handed-off-call)
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.
