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

# Twilio SMS Integration with WorldVisa

> Connect Twilio to WorldVisa to send SMS notifications through workflows. Store your Twilio account SID, auth token, and sender phone number in the WorldVisa dashboard.

You can utilize the [Twilio](https://www.twilio.com/) API to communicate with your customers using SMS messaging. Let's look at how you can do that:

## Setting up Twilio

**1. Create a Twilio Account**

1. Go to [Twilio](https://www.twilio.com/) and create an account, starting with their free trial.
2. You'll be asked to verify your email and your phone number. Get them verified.

**2. Get a Twilio Phone Number**

1. Once verified, you'll get an option to 'get a Twilio phone number' from your Twilio console.
2. Click on it to get your Twilio phone number.

> [!NOTE]
>
> When first using Twilio there should be an option to get a Twilio phone number in the main
> console. Otherwise, you may have to
> [Buy](https://console.twilio.com/us1/develop/phone-numbers/manage/search?frameUrl=%2Fconsole%2Fphone-numbers%2Fsearch%3Fx-target-region%3Dus1\&currentFrameUrl=%2Fconsole%2Fphone-numbers%2Fsearch%3FisoCountry%3DUS%26searchTerm%3D%26searchFilter%3Dleft%26searchType%3Dnumber%26x-target-region%3Dus1%26__override_layout__%3Dembed%26bifrost%3Dtrue)
> a number to begin using it. For first-time users, utilize the free number provided.

For more detailed instructions, follow one of their many [Tutorials](https://www.twilio.com/docs/usage/requests-to-twilio) within their docs.

**3. Understand the Key Components**

Irrespective of the language you use, the process requires:

1. Account SID and Auth token loaded into the code using secure environment variables
2. A Twilio client object that takes the SID and Token as variables
3. A message object containing:

* Your Twilio phone number
  * The recipient's phone number
  * The SMS message body

## Creating a Twilio integration with WorldVisa

**1. Connect Twilio to WorldVisa**

1. Visit the Integrations Store on WorldVisa
2. Click the "Add a provider" button
3. Locate **Twilio** and click on the `Disabled` button and mark it as `Active`
4. Click on the **Connect** button

**2. Configure Twilio Credentials**

1. Go to your [Console](https://console.twilio.com/) on Twilio and access the Account Info section
2. Enter your:
   * `Account SID`
   * `Authentication method` — keep **Auth token**, or select **API key** to [use a Twilio API key](#authenticate-with-an-api-key)
   * `Auth Token`
   * `Twilio Phone Number`
3. Click on the **Save** button

## Authenticate with an API key

Use a Twilio API key instead of your account Auth Token when you do not want to share the Auth Token with WorldVisa. You can revoke an API key at any time without affecting other apps that use your Twilio account.

**1. Create an API key in Twilio**

In the Twilio Console, go to **Account** > **API keys & tokens** and create an API key. A **Restricted** key needs only permission to create messages. Copy the key's **SID** (starts with `SK`) and **Secret**. Twilio shows the secret only once.

**2. Select API key in WorldVisa**

In your Twilio integration, set **Authentication method** to **API key**, then enter your `Account SID`, `API Key SID`, and `API Key Secret`. WorldVisa removes the stored Auth Token when you save.

> [!NOTE]

To configure API key authentication through the WorldVisa API, set `authMethod` to `apiKey` and send the key in `apiKey` (API Key SID) and `secretKey` (API Key Secret) inside `credentials`. WorldVisa does not store `token` in this mode. To use the Auth Token, leave `authMethod` out.

Twilio supports processing and storing SMS data in specific regions. WorldVisa lets you choose the API region when connecting your Twilio integration.

| Region | Twilio region | When to use |
| - | - | - |

> [!NOTE]

**1. Create IE1 API credentials**

In the Twilio Console, create API credentials for the **IE1** region. Use those credentials in your WorldVisa Twilio integration instead of your US credentials.

**2. Configure senders for IE1**

If you send with phone numbers, set each number's active messaging region to **IE1** in the Twilio Console under **Numbers & Senders**.

**3. Select EU in WorldVisa**

Select the matching EU region when configuring this integration in WorldVisa.

## Sending WhatsApp message

To send WhatsApp messages with Twilio integration, prefix the phone number of the subscriber with `whatsapp:` as shown below:

```bash theme={null}
curl --location "${WV_API_URL}/v1/events/trigger" \
--header 'Content-Type: application/json' \
--header "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId",
        "phone": "whatsapp:+14155238886"
    },
    "payload": {},
    "overrides": {
        "providers": {
            "twilio": {
                "_passthrough": {
                    "body": {
                        "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                        "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                    }
                }
            }
        }
    }
}'
```

### Sending WhatsApp template message

To send WhatsApp template messages with Twilio integration, you can use the `template` field in the `overrides` object.

```bash theme={null}
curl --location "${WV_API_URL}/v1/events/trigger" \
--header 'Content-Type: application/json' \
--header "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId",
        "phone": "whatsapp:+14155238886"
    },
    "payload": {},
    "overrides": {
        "providers": {
            "twilio": {
                "_passthrough": {
                    "body": {
                        "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                        "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                    }
                }
            }
        }
    }
}'
```

> [!NOTE]
>
> Read more about [sending a Message with the Twilio API for
> WhatsApp](https://www.twilio.com/docs/whatsapp/tutorial).


## Related topics

- [SMS](https://docs.worldvisagroup.com/developers/integrations/sms.md)
- [Azure SMS SMS Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/sms/azure.md)
- [SMS Webhook SMS Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/sms/sms-webhook.md)
- [SMS Central SMS Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/sms/sms-central.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.