# Twilio
{% hint style="info" %}
The following documentation is for **Twilio v2.0.1** *(BDK)*.
{% endhint %}
## Overview
Twilio is a cloud communications platform providing SMS, voice, video, and messaging API services. This integration enables automated SMS sending, phone call management, communication workflows, and customer engagement automation. Enhance customer communication and automate messaging processes.
## Prerequisites
### 1. Required Books
The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:
* **Twilio**
#### How to Add the Book(s)
1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on **Install** or **Add Connection** to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.
## Connectivity
This section outlines the available methods for connecting to the Book, along with the required configuration details for each.
### Connect using Account SID and Auth Token
Connect to the Twilio API using account credentials.
| Label | Description | Type |
| ----------- | ----------------------------------------- | ----------- |
| Account SID | The Account SID from your Twilio account. | `text` |
| Auth Token | The Auth Token from your Twilio account. | `sensitive` |
## Procedures
### to read some (*SMS* messages)
Get SMS messages from the Twilio API.
**Output Concepts**
| Concept | Description | Type |
| ------------------------------------- | -------------------------------------------------------------------- | -------------------- |
| [`SMS messages`](#twilio-sms-message) | A list of SMS messages that matches the specified filtering criteria | `twilio sms message` |
**Examples**
Retrieve SMS messages filtered by sender and recipient numbers
```generic
read some sms messages whose sender number is "+18004445555" and whose recipient number is "+18004446666"
```
Retrieve SMS messages filtered by the date in which they were sent
```generic
convert "2022-03-01T15:00:00Z" to a datetime
use the above as the message date
read some sms messages whose date sent is the message date
```
Retrieve SMS messages that were sent in the specified time period
```generic
convert "2022-03-01T15:00:00Z" to a datetime
use the above as the start date
convert "2022-03-03T15:00:00Z" to a datetime
use the above as the end date
read some sms messages whose date sent is after the start date and whose date sent is before the end date
```
### to send an *SMS* message
Send an SMS message using the Twilio API.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ------------------ | ------------------------------------------------ | ------ | -------- | ------------- |
| `sender number` | The Twilio phone number to send the message from | `text` | Yes | (no default) |
| `recipient number` | The recipient's phone number | `text` | Yes | (no default) |
| `message body` | The body of the SMS message to send | `text` | Yes | (no default) |
**Output Concepts**
| Concept | Description | Type |
| -------- | ---------------------------------------------------------- | ------ |
| `answer` | The SID of the sent message if successful, otherwise None. | `text` |
**Examples**
Send an SMS message
```generic
send an SMS message where
the sender number is "+18004445555"
the recipient number is "+18004446666"
the message body is "Hello from Kognitos!"
```
## Concepts
### Twilio sms message
SMS message data model.An SMS (Short Message Service) message. Represents a text communication sent over a cellular network, typically between mobile phones.
| Field Name | Description | Type |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `sid` | The unique, Twilio-provided string that identifies the Message resource. | `optional[text]` |
| `body` | The text content of the message | `optional[text]` |
| `num_segments` | The number of segments that make up the complete message. SMS message bodies that exceed the [character limit](https://www.twilio.com/docs/glossary/what-sms-character-limit) are segmented and charged as multiple messages. Note: For messages sent via a Messaging Service, `num_segments` is initially `0`, since a sender hasn't yet been assigned | `optional[text]` |
| `sender_number` | The sender's phone number (in [E.164](https://en.wikipedia.org/wiki/E.164) format), [alphanumeric sender ID](https://www.twilio.com/docs/sms/quickstart), [Wireless SIM](https://www.twilio.com/docs/iot/wireless/programmable-wireless-send-machine-machine-sms-commands), [short code](https://www.twilio.com/en-us/messaging/channels/sms/short-codes), or [channel address](https://www.twilio.com/docs/messaging/channels) (e.g., `whatsapp:+15554449999`). For incoming messages, this is the number or channel address of the sender. For outgoing messages, this value is a Twilio phone number, alphanumeric sender ID, short code, or channel address from which the message is sent | `optional[text]` |
| `recipient_number` | The recipient's phone number (in [E.164](https://en.wikipedia.org/wiki/E.164) format) or [channel address](https://www.twilio.com/docs/messaging/channels) (e.g. `whatsapp:+15552229999`) | `optional[text]` |
| `price` | The amount billed for the message in the currency specified by `price_unit`. The `price` is populated after the message has been sent/received, and may not be immediately available. View the [Pricing page](https://www.twilio.com/en-us/pricing) for more details. | `optional[number]` |
| `account_sid` | The SID of the [Account](https://www.twilio.com/docs/iam/api/account) associated with the Message resource | `text` |
| `num_media` | The number of media files associated with the Message resource. | `number` |
| `status` | The status of the message, for more information about possible statuses see [Message Status](https://www.twilio.com/docs/messaging/api/message-resource#message-status-values) | `optional[text]` |
| `messaging_service_sid` | The SID of the [Messaging Service](https://www.twilio.com/docs/messaging/api/service-resource) associated with the Message resource. A unique default value is assigned if a Messaging Service is not used. | `text` |
| `date_sent` | The [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822#section-3.3) timestamp (in GMT) of when the Message was sent. For an outgoing message, this is when Twilio sent the message. For an incoming message, this is when Twilio sent the HTTP request to your incoming message webhook URL. | `optional[datetime]` |
| `date_created` | The [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822#section-3.3) timestamp (in GMT) of when the Message resource was created | `optional[datetime]` |
| `date_updated` | The [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822#section-3.3) timestamp (in GMT) of when the Message resource was last updated | `optional[datetime]` |
| `price_unit` | The currency in which `price` is measured, in [ISO 4127](https://www.iso.org/iso/home/standards/currency_codes.htm) format (e.g. `usd`, `eur`, `jpy`). | `text` |
| `error_code` | The [error code](https://www.twilio.com/docs/api/errors) returned if the Message `status` is `failed` or `undelivered`. If no error was encountered, the value is `null`. | `optional[number]` |
| `error_message` | The description of the `error_code` if the Message `status` is `failed` or `undelivered`. If no error was encountered, the value is `null`. | `optional[text]` |