> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/twilio

Create custom Twilio SMS notifications for CircleCI jobs. Check the linked API docs for further information.
Requires "Option 2" environment variables to be created, as detailed here:
https://www.twilio.com/docs/twilio-cli/general-usage#want-to-use-environment-variables-instead-of-creating-a-profile


## Commands

### alert

Send SMS alert on failure only. This must be the last step in the job to work properly.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `authtoken` | env_var_name | TWILIO_AUTH_TOKEN | API authorization token for your Twilio account. |
| `body` | string | Notification from CircleCI. A critical test has failed. | The Body parameter includes the full text of the message you want to send, limited to 1600 characters. |
| `from` | string | ${TWILIO_FROM} | This must be a Twilio phone number that you own, formatted with a '+' and country code,
  e.g. +16175551212 (E.164 format). You can also use a Messaging Service SID.
 |
| `sid` | string | TWILIO_ACCOUNT_SID | Twilio account SID. |
| `to` | string | ${TWILIO_TO} | This parameter determines the destination phone number for your SMS message. Format this number with a '+' and a country code, e.g., +16175551212 (E.164 format).
 |

### install

Install the Twilio CLI from npm. Requires node - most commands will fall back to using curl requests if the CLI cannot be found.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string | latest | Version of the Twilio CLI package to install. Defaults to latest. |

### sendsms

Send SMS notifications using Twilio

| Parameter | Type | Default | Description |
|---|---|---|---|
| `authtoken` | env_var_name | TWILIO_AUTH_TOKEN | API authorization token for your Twilio account. |
| `body` | string | Notification from CircleCI. You have not yet customized your message. | The Body parameter includes the full text of the message you want to send, limited to 1600 characters. |
| `from` | string | ${TWILIO_FROM} | This must be a Twilio phone number that you own, formatted with a '+' and country code,
  e.g. +16175551212 (E.164 format). You can also use a Messaging Service SID.
 |
| `sid` | string | TWILIO_ACCOUNT_SID | Twilio account SID. |
| `to` | string | ${TWILIO_TO} | This parameter determines the destination phone number for your SMS message. Format this number with a '+' and a country code, e.g., +16175551212 (E.164 format).
 |

## Examples

### alert

This function is the same as the "sendsms" command but will only run when the job has failed. This must be the last step in a job to work properly.


```yaml
orbs:
  jobs:
    build:
      docker:
        - image: cimg/node:14.4.0
      steps:
        - twilio/install
        - twilio/alert:
            body: Customize alert message for this job
            from: '+15005550006'
            to: '+15005550006'
  twililo: circleci/twilio@volatile
version: 2.1
```

### send-sms

Send an SMS with a custom message.


```yaml
orbs:
  jobs:
    build:
      docker:
        - image: cimg/base:edge
      steps:
        - twilio/install
        - twilio/sendsms:
            body: This is a custom message notification
            from: '+15005550006'
            to: '+15005550006'
  twililo: circleci/twilio@x.y.z
version: 2.1
```