Cameleer

Twilio component

The twilio component calls the Twilio REST API (2010-04-01): send and list SMS and MMS messages, place calls, manage phone numbers, queues, recordings and the other resources Camel's twilio component exposes.

Scheme: twilio: · Crate: cameleer-saas · Cargo feature: saas · Consumer: no · Producer: yes · Apache Camel: Twilio

When to use it

  • Send an SMS when an alert fires, an order ships or an IoT sensor crosses a threshold.
  • Let an AI agent text a short summary to the on-call phone.
  • Read the message log, or fetch a message's delivery status.
  • Automate calls, queues, phone numbers or usage reports.

URI format

text
twilio:api/method[?options]

api is a Twilio resource in Camel's naming (message, call, queue, incoming-phone-number, recording, usage-record-today, ...). method is create, read, fetch, update or delete (or Camel's creator, reader, fetcher, updater, deleter). Unsupported combinations fail when the endpoint is created.

Example

Send an SMS. For message/create the body is the message text unless a body or mediaUrl parameter is set. After the call the body is the created message (sid, status, ...).

yaml example: twilio-send-sms
- route:
    id: sms-alert
    from:
      uri: "direct:sms-alert"
      steps:
        - setBody:
            simple: "ALERT ${header.device}: temperature ${header.celsius} C"
        - to: "twilio:message/create?from=RAW({{env:TWILIO_FROM:+15005550006}})&to=RAW({{env:ONCALL_PHONE:+15005550001}})&username={{env:TWILIO_ACCOUNT_SID}}&password={{env:TWILIO_AUTH_TOKEN}}&serverUrl={{env:TWILIO_API_URL:https://api.twilio.com}}"
        - log: "sent SMS ${body[sid]}"

List the messages sent to a number. read returns the resource list as the body; every parameter that is not a path* parameter becomes a query filter (to → To).

yaml example: twilio-read-messages
- route:
    id: sms-log
    from:
      uri: "timer:sms-log?repeatCount=1"
      steps:
        - to: "twilio:message/read?to=RAW({{env:ONCALL_PHONE:+15005550001}})&username={{env:TWILIO_ACCOUNT_SID}}&password={{env:TWILIO_AUTH_TOKEN}}&serverUrl={{env:TWILIO_API_URL:https://api.twilio.com}}"
        - split:
            simple: "${body}"
            steps:
              - to: "log:sms-log"

Rust DSL

rust
ctx.add_routes(|b| {
    b.from("direct:sms-alert")
        .set_body(simple("ALERT ${header.device}: temperature ${header.celsius} C"))
        .to("twilio:message/create?from=RAW(+15005550006)&to=RAW(+15005550001)&username={{env:TWILIO_ACCOUNT_SID}}&password={{env:TWILIO_AUTH_TOKEN}}");
})?;

Options

optiondefaultdescription
usernameAccount SID (or API key SID), required.
passwordAuth token (or API key secret), required.
accountSidusernameAccount the resources belong to (Accounts/{accountSid}/...).
inBodyName of the parameter taken from the message body (default body for message/create).
serverUrlhttps://api.twilio.comAPI base URL (Cameleer extension: a proxy or a test server).
path*Resource path parameters: pathSid (the instance for fetch, update, delete), pathAccountSid, pathCallSid, pathConferenceSid, pathQueueSid, pathMessageSid, pathCountryCode, ...
any otherSent to Twilio as a form field (create, update) or query parameter (read), with the Twilio capitalisation: to → To, statusCallback → StatusCallback.

Because every unknown option is an API parameter, a misspelled option is sent to Twilio rather than rejected when the endpoint is created.

Message headers

headerdirectiondescription
CamelTwilio.<parameter>inAny API parameter, for example CamelTwilio.to or CamelTwilio.pathSid. Headers win over endpoint options. List values repeat the field.

The body after the call: the created, fetched or updated resource as a map; the resource list for read; true for delete.

Run it with Docker

sh
export TWILIO_ACCOUNT_SID=AC... TWILIO_AUTH_TOKEN=... TWILIO_FROM=+1... ONCALL_PHONE=+1...
docker run --rm -e TWILIO_ACCOUNT_SID -e TWILIO_AUTH_TOKEN -e TWILIO_FROM -e ONCALL_PHONE \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/sms-log.camel.yaml

Common questions

How do I send to a different number per message?

Set the CamelTwilio.to header before the endpoint; it overrides the to option.

Why do phone numbers need RAW(...)?

In an endpoint URI a + is decoded as a space, as in Apache Camel, so to=+15005550001 would reach Twilio as 15005550001. Write to=RAW(+15005550001) or to=%2B15005550001, or set the number in the CamelTwilio.to header, which is not URI-decoded.

How do I send an MMS?

Add mediaUrl=https://example.com/chart.png (or the CamelTwilio.mediaUrl header, a list for several images). Set inBody=body if the body should still be the text.

What happens when Twilio rejects a request?

The exchange fails with HttpOperationFailedException; the message contains the HTTP status, the Twilio error code and message (for example code: 21211, message: Invalid 'To' Phone Number).

Is there a consumer for incoming SMS?

No. Twilio pushes incoming messages with webhooks; receive them with platform-http and point the number's messaging webhook at that URL.

Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building with it, please help fix it, whether you are a person or a coding agent: open an issue that describes what you saw, then fork the repository, fix it, add or update a test, run cargo test --workspace, and open a pull request. CONTRIBUTING.md explains the ground rules.

Edit this page on GitHub