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

# Twilio (SMS, Voice, WhatsApp)

> Client-mode REST API connector for a curated Twilio v2010 slice: send SMS/WhatsApp, outbound voice calls with TwiML, list messages/calls, and account credential smoke

Technical Preview

## Overview

A client-mode connector for a **curated messaging/voice** slice of the [Twilio REST API](https://www.twilio.com/docs/usage/api) (v2010-04-01):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST Messages.json | `POST /2010-04-01/Accounts/{AccountSid}/Messages.json` | SMS from alarm; WhatsApp via `whatsapp:+E164` |
| POST Calls.json | `POST /2010-04-01/Accounts/{AccountSid}/Calls.json` | Voice alert with `Url` or inline `Twiml` |
| GET Messages.json | `GET /2010-04-01/Accounts/{AccountSid}/Messages.json` | List recent messages |
| GET Calls.json | `GET /2010-04-01/Accounts/{AccountSid}/Calls.json` | List recent calls |
| GET Account (smoke) | `GET /2010-04-01/Accounts/{AccountSid}.json` | Credential check |

Default `BASE_ADDRESS` is `https://api.twilio.com`. Topics use `messaging/twilio/<object>/<verb>`.

> [!NOTE]
>
> Twilio authenticates with **HTTP Basic** (Account SID + Auth Token, or API Key SID + secret). Create Message/Call bodies use `application/x-www-form-urlencoded`, not JSON. The Verify API (`verify.twilio.com`) and inbound SMS webhook → MQTT are out of scope for this client-mode package. Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Twilio
# Auth: HTTP Basic (Account SID + Auth Token) or Basic {value.json.basic_b64}
# BASE_ADDRESS: https://api.twilio.com

DEFINE ROUTE TwilioRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.twilio.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/x-www-form-urlencoded"
        # Optional config-level Basic:
        # WITH USERNAME "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        # WITH PASSWORD GET SECRET "TWILIO_AUTH_TOKEN"
    ADD EVENT Getaccount
        WITH SOURCE_TOPIC "messaging/twilio/account/get"
        WITH DESTINATION_TOPIC "messaging/twilio/account/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2010-04-01/Accounts/{value.json.account_sid}.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Createmessage
        WITH SOURCE_TOPIC "messaging/twilio/message/send"
        WITH DESTINATION_TOPIC "messaging/twilio/message/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/2010-04-01/Accounts/{value.json.account_sid}/Messages.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{payload}"
    ADD EVENT Listmessages
        WITH SOURCE_TOPIC "messaging/twilio/message/list"
        WITH DESTINATION_TOPIC "messaging/twilio/message/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2010-04-01/Accounts/{value.json.account_sid}/Messages.json?PageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Createcall
        WITH SOURCE_TOPIC "messaging/twilio/call/create"
        WITH DESTINATION_TOPIC "messaging/twilio/call/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/2010-04-01/Accounts/{value.json.account_sid}/Calls.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{payload}"
    ADD EVENT Listcalls
        WITH SOURCE_TOPIC "messaging/twilio/call/list"
        WITH DESTINATION_TOPIC "messaging/twilio/call/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2010-04-01/Accounts/{value.json.account_sid}/Calls.json?PageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getaccount | GET | `/2010-04-01/Accounts/{AccountSid}.json` | `messaging/twilio/account/get` | `messaging/twilio/account/get/response` |
| Createmessage | POST | `/2010-04-01/Accounts/{AccountSid}/Messages.json` | `messaging/twilio/message/send` | `messaging/twilio/message/send/response` |
| Listmessages | GET | `/2010-04-01/Accounts/{AccountSid}/Messages.json` | `messaging/twilio/message/list` | `messaging/twilio/message/list/response` |
| Createcall | POST | `/2010-04-01/Accounts/{AccountSid}/Calls.json` | `messaging/twilio/call/create` | `messaging/twilio/call/create/response` |
| Listcalls | GET | `/2010-04-01/Accounts/{AccountSid}/Calls.json` | `messaging/twilio/call/list` | `messaging/twilio/call/list/response` |

## Auth

1. Create (or open) a Twilio account and copy the **Account SID** and **Auth Token** from the Console (or create an **API Key** SID + secret for production).
2. Set connector `BASE_ADDRESS` to `https://api.twilio.com`.
3. Configure Basic auth via Hub secrets (`WITH USERNAME` / `WITH PASSWORD GET SECRET "TWILIO_AUTH_TOKEN"`) **or** pass `basic_b64` (base64 of `sid:token`) on each MQTT payload.
4. Pass `account_sid` on every request so path placeholders resolve.
5. Never commit real credentials. Successful account fetch returns **HTTP 200**; create Message/Call typically returns **HTTP 201**.

## Example payloads

**getAccount:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "basic_b64": "BASE64_OF_SID_COLON_TOKEN"
}
```

**createMessage (form body string for `{payload}`):**

```
To=%2B15558675310&From=%2B15557122661&Body=Coreflux%20alarm%3A%20Zone%20A
```

**createMessage WhatsApp:**

```
To=whatsapp%3A%2B15557770006&From=whatsapp%3A%2B15555238886&Body=Coreflux%20alarm
```

**createCall (inline TwiML):**

```
To=%2B15558675310&From=%2B15557122661&Twiml=%3CResponse%3E%3CSay%3ECoreflux%20alarm%3C%2FSay%3E%3C%2FResponse%3E
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)
* [Twilio Message resource](https://www.twilio.com/docs/messaging/api/message-resource)
* [Twilio Call resource](https://www.twilio.com/docs/voice/api/call-resource)


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