> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sentivue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Twilio

> Configure Twilio for voice communication in SentiVue Talk

## Overview

Twilio is a cloud communications platform that enables voice calling, messaging, and video capabilities. SentiVue Talk's Twilio integration provides seamless connectivity for your workflows.

## Prerequisites

Before setting up Twilio integration, you'll need:

* A [Twilio account](https://www.twilio.com/try-twilio)
* Account SID and Auth Token from your Twilio Console
* At least one Twilio phone number
* A SentiVue Talk account

## Configuration

### Step 1: Get Twilio Credentials

1. Log in to your [Twilio Console](https://console.twilio.com/)
2. Find your **Account SID** and **Auth Token** on the dashboard
3. Navigate to **Phone Numbers** → **Manage** → **Active Numbers**
4. Copy your phone number(s)

### Step 2: Configure in SentiVue Talk

1. Navigate to **/telephony-configurations** and click **Add configuration**
2. Select **Twilio** as your provider
3. Enter your credentials:
   * Account SID
   * Auth Token
4. Click **Save Configuration**
5. Open the configuration you just created and add at least one **phone number** (with country code in E.164 format, e.g. `+1234567890`). The default caller ID is used for outbound calls.

### Step 3: Test Your Configuration

1. Create a test workflow
2. Click "Call" to verify connection
3. Check call logs for successful connection

## Inbound Calling Setup

Inbound routing is driven by the phone number itself — there is a **single webhook URL** for the entire org, and SentiVue Talk resolves which agent to run from the called number's assigned inbound workflow. **When you save an inbound workflow on a phone number, SentiVue Talk automatically pushes the webhook URL to that number's `VoiceUrl` in your Twilio account** (provided the credentials are correct and the number belongs to that account).

### Step 1: Assign an Inbound Workflow to the Phone Number

1. Go to **/telephony-configurations** and open your Twilio configuration
2. In the **Phone numbers** section, edit the number that should receive inbound calls
3. Set its **Inbound workflow** to the agent that should answer
4. Save

### Step 2: Verify the Webhook URL in Twilio Console

<Note>
  This step applies to numbers using the **Standard** setup. Numbers on the [Advanced setup](#call-handling-setup) receive calls over a SIP trunk instead, and have no voice webhook to verify — skip to Step 3.
</Note>

1. Go to **Phone Numbers** → **Manage** → **Active Numbers** in Twilio Console
2. Click the phone number you assigned an inbound workflow to in Step 1
3. In the **Voice Configuration** section, confirm:

   * **Webhook** is set to: `https://app.sentivue.com/talk/api/v1/telephony/inbound/run`
   * **HTTP Method** is `POST`

   SentiVue Talk sets this automatically when you save the inbound workflow.

   If the field is empty or shows something else, the auto-push failed — usually wrong credentials, or a number this Twilio account does not own. Paste the URL in yourself, set the method to `POST`, and click **Save Configuration**.

### Step 3: Verify Setup

* Confirm the number appears in your Twilio configuration under **/telephony-configurations**, in E.164 format, and matches the number in Twilio Console exactly
* Confirm the number has an **Inbound workflow** assigned

### Test Inbound Calling

1. Call your configured Twilio phone number from another phone
2. Verify your SentiVue Talk workflow answers and responds
3. Check call logs in both SentiVue Talk dashboard and Twilio Console

## Call handling setup

The setup is chosen **per number**, not per configuration. You pick it when you add a number, and you can switch an existing number at any time.

**Standard** is the TwiML setup. Calls reach your agent through Twilio's voice webhook. Nothing to configure beyond adding the number.

**Advanced** is the Elastic SIP setup. Calls are carried over a SIP trunk instead of the webhook, which is what warm transfer and live translation need.

One Twilio configuration can hold a mix of both. A support line can stay on Standard while a sales line uses Advanced, in the same account, at the same time. Switching one number does not affect any other.

|                                   | Standard | Advanced      |
| --------------------------------- | -------- | ------------- |
| Inbound and outbound agent calls  | Yes      | Yes           |
| Cold transfer                     | Yes      | Yes           |
| Warm transfer                     | No       | Yes           |
| Live translation                  | No       | Yes           |
| Transfers on web and widget calls | No       | Yes           |
| Setup time                        | None     | A few seconds |

Use Standard unless you need warm transfer or translation. Advanced creates real resources in your Twilio account, so there is no reason to enable it on numbers that will not use those features.

### Switching a number to Advanced

1. Open your Twilio configuration under **Telephony configurations**.
2. Add a number, or click an existing one to edit it.
3. Under **Call handling**, select **Advanced**.
4. Save.

Saving takes a few seconds because SentiVue Talk configures your Twilio account while you wait. The button shows **Provisioning** until it finishes.

### What Advanced creates in your Twilio account

* **An Elastic SIP Trunk** — one per Twilio account, not one per number. The first number you switch to Advanced creates it, and every Advanced number after that reuses it.
* **A credential list and SIP credential** on that trunk, used to authenticate the connection.
* **An origination URI**, so calls on the trunk reach your workflows.
* **The number is attached to the trunk.** Its voice traffic is handled by the trunk from then on, and SentiVue Talk clears the number's **Voice webhook** field since it is no longer used.

<Warning>
  Do not edit or delete the SIP trunk, its credential list, or its origination URI from the Twilio Console. The trunk is shared by every Advanced number on the account, so changing it affects all of them at once.
</Warning>

### If setup fails

Switching a working Standard number to Advanced is safe. If provisioning fails, the number goes back to Standard, its webhook is restored, and it keeps taking calls. The number shows a failed setup, and you can select Advanced again to retry.

If a retry fails, the number stays on Advanced and marked failed rather than falling back, since there is no working Standard setup to return to. Retry again once the cause is fixed.

### Switching back to Standard

Select **Standard** on the number and save. SentiVue Talk removes the number from the trunk and restores its voice webhook.

Switching back the **last** Advanced number on an account, or deleting it, also removes the shared SIP trunk and its credentials, since nothing else is using them. Numbers still on Advanced are unaffected.

<Warning>
  Switching back to Standard disables warm transfer and translation on any transfer tool that dials out from that number, and those tools will stop working. Point them at another Advanced number first if you still need them.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Advanced setup failed">
    Usually the Twilio credentials lack permission to manage Elastic SIP Trunking, or the number is not owned by the Twilio account in this configuration. Confirm both, then select Advanced again to retry.
  </Accordion>

  <Accordion title="Inbound calls stopped after switching to Advanced">
    Advanced numbers still need an **Inbound workflow** assigned so SentiVue Talk knows which agent should answer. Check that assignment on the number.
  </Accordion>

  <Accordion title="The number is not offered when setting up a warm transfer">
    Only Advanced numbers on the selected telephony configuration appear. Confirm the number shows Advanced, that its setup succeeded, and that you picked the right configuration on the tool.
  </Accordion>

  <Accordion title="Invalid phone number error">
    Ensure phone numbers include country code in E.164 format: `+1234567890`
  </Accordion>

  <Accordion title="Authentication failed">
    * Verify Account SID and Auth Token are correct - Check for extra spaces in
      credentials - Ensure credentials haven't been regenerated in Twilio Console
  </Accordion>

  <Accordion title="Webhook signature validation failing">
    * Confirm the Auth Token in your SentiVue Talk configuration matches the one
      in Twilio Console exactly - Verify the number's webhook URL in Twilio Console is
      `https://app.sentivue.com/talk/api/v1/telephony/inbound/run` with no extra query
      parameters or trailing characters
  </Accordion>

  <Accordion title="No audio on calls">
    Review the call in your SentiVue Talk dashboard and in Twilio Console under
    **Monitor** → **Logs** → **Calls** for errors on that call.
  </Accordion>

  <Accordion title="Inbound calls go to voicemail">
    * Verify the Twilio number's webhook is set to
      `https://app.sentivue.com/talk/api/v1/telephony/inbound/run` with the HTTP method `POST` - Confirm the called number exists in your SentiVue Talk telephony configuration and has an **Inbound workflow** assigned - Confirm the number is stored in E.164 format and matches the number in Twilio Console exactly - Check the call in Twilio Console under **Monitor** → **Logs** → **Calls** to see the response the webhook returned
  </Accordion>

  <Accordion title="Voice agent doesn't respond to inbound calls">
    * Confirm the phone number has an **Inbound workflow** assigned in
      /telephony-configurations - Check webhook signature validation is working (Auth Token in SentiVue Talk matches Twilio Console) - Review call logs in your SentiVue Talk dashboard for error messages - Check the response the webhook returned in Twilio Console under **Monitor** → **Logs** → **Calls**
  </Accordion>
</AccordionGroup>

## Best Practices

* Test your configuration with a single call before running campaigns
* Monitor Twilio Console for usage and billing