> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/sms/integrations/providers/twilio.md).

# Twilio

Connect Twilio to SMS — send real text messages from a Twilio number you own.

Twilio carries your SMS to carriers worldwide, from a Twilio phone number you own. It is the real provider Norbix sends through today.

## Get your credentials

1. Sign in to the [Twilio Console](https://console.twilio.com/).
2. On the account dashboard, under **Account Info**, copy the **Account SID** (starts with `AC`) and the **Auth Token**.
3. Under **Phone Numbers → Manage → Active numbers**, pick a number that can send SMS and note it in E.164 format, e.g. `+15551234567`. A trial account sends only to the numbers you verified in Twilio.

## Connect it in Cloud

**Where:** SMS → Integrations → **Add New Integration** → Twilio → **Connect** · `/projects/<project>/sms/integrations/new/twilio`

The form is titled **New Twilio Integration**. Fill it and press **Save**; the integration is saved enabled.

| Field               | Required | What it does                                                                                                                                            | Example                                        |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| Account SID         | yes      | Names your Twilio account; paired with the Auth Token.                                                                                                  | `AC0000000000000000000000000000docs` (made up) |
| Sender Phone Number | yes      | The number every SMS of this integration comes from, in E.164 format. It must be a number in your Twilio account; only its presence is checked on save. | `+15550001234`                                 |
| Auth Token          | yes      | Secret. Encrypted on save and never shown again — an edit needs it typed again (`CM-ERRORS-SECRETS-001`, *Secret is not provided*).                     | `your-twilio-auth-token`                       |
| Integration Name    | yes      | The name in your integrations list.                                                                                                                     | `Twilio (Acme support line)`                   |

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-f77582fed1a385962f4b997174041a8dfff96127%2Ftwilio-form-1.png?alt=media" alt="New Twilio Integration form filled in: Account SID, Sender Phone Number +15550001234, the hidden Auth Token, the info box about secrets, Integration Name Twilio (Acme support line), Cancel and Save"><figcaption><p>The filled form.</p></figcaption></figure>

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-69c03ce285ba629c04290b8dd9e2581799348373%2Ftwilio-saved-2.png?alt=media" alt="Editing Twilio integration after save: the badges ENABLED, TEST FAILED, NOT CONFIRMED, the int_ id, the saved fields with an empty Auth Token, and the test panel with Test SMS Recipient and Test integration"><figcaption><p>After save: the integration page with its badges and test panel.</p></figcaption></figure>

## Test and set as default

Type your phone under **Test SMS Recipient** and press **Test integration**. Norbix first signs in to Twilio (**CheckCredentials**, no SMS, no cost), then sends a real SMS to that number; when it arrives, press **I received it**. See [Test an integration](/codemash/cloud/sms/integrations/test.md). Then choose **Actions → Set as default** so Cloud picks it for you on new campaigns, trigger actions and template tests — see [Set an integration as default](/codemash/cloud/sms/integrations/set-default.md).

Each SMS is one call to Twilio's Messages API. Twilio's first answer (*queued*) is the last status Norbix learns: a message Twilio accepts counts as sent, and a later carrier failure is not shown.

## Common errors

| Message                                                                                                                 | Cause                                                                      | Fix                                                                                 |
| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Twilio refused the SMS request with HTTP 401 Unauthorized. Authentication Error - invalid username (Twilio error 20003) | Wrong Account SID or Auth Token.                                           | Copy both again from the Twilio Console, type the Auth Token, **Save**, test again. |
| Twilio error 21211                                                                                                      | The number is not valid, or a trial account sends to an unverified number. | Use a valid E.164 number; verify it in Twilio or upgrade the account.               |
| Please enter a valid phone number in E.164 format (e.g. +15551234567).                                                  | The test recipient is not in E.164 format.                                 | Type `+`, the country code and the digits.                                          |
| Secret is not provided (`CM-ERRORS-SECRETS-001`)                                                                        | A save without the Auth Token.                                             | Type the Auth Token again on every save.                                            |

## Do it from code

```ts
const { id } = await norbix.hub.notifications.saveSmsIntegration({
  integration: {
    provider: 'Twilio',
    integrationName: 'Twilio (night shift line)',
    isEnabled: true,
    accountSid: 'AC0000000000000000000000000000docs',
    fromPhoneNumber: '+15550004321',
    authToken: 'your-twilio-auth-token',
  } as any, // the TS type knows only the shared fields
});
console.log(id); // int_…
```

```sh
norbix hub notifications sms integration save --integration '{"provider":"Twilio","integrationName":"Twilio (night shift line)","isEnabled":true,"accountSid":"AC0000000000000000000000000000docs","fromPhoneNumber":"+15550004321","authToken":"your-twilio-auth-token"}'
```

Send `isEnabled: true` — on the API it defaults to off. To update, send the id as `integrationId` and the Auth Token again. The client setup is on the [SMS page](/codemash/cloud/sms.md#use-it-from-code). API: [Save Sms Integration](/codemash/api-reference/notifications/sms/save-sms-integration.md)