Twilio

Twilio

This connector works with one Twilio account through the Twilio REST API: messages (SMS, MMS and WhatsApp) on https://api.twilio.com/2010-04-01, calls, owned phone numbers, account balance and usage, Messaging Services, Lookup v2 (https://lookups.twilio.com/v2) and Verify v2 (https://verify.twilio.com/v2) for one-time codes.

Setup (about 3 minutes)

1. Sign in at https://console.twilio.com. The Account Info panel on the start page shows the Account SID (starts with AC) and the Auth Token.
2. Recommended: create an API key instead of using the Auth Token. In the Console open Settings → Account settings → API keys & auth tokens (in the legacy Console Admin → Account management → API keys & tokens), click Create API key, choose the type Standard and copy the SID (starts with SK) and the Secret; the secret is shown only once. A key can be revoked on its own without changing the Auth Token. A Standard key may not read the account record itself (twilio_get_account then answers 401 or 403); everything else works.
3. Fill in TWILIO_ACCOUNT_SID with the Account SID, and either TWILIO_API_KEY_SID = the key SID (SK...) and TWILIO_API_KEY_SECRET = its secret, or TWILIO_API_KEY_SID = the Account SID again (AC...) and TWILIO_API_KEY_SECRET = the Auth Token.
4. Install and run twilio_list_phone_numbers.

Sending costs money and reaches real people: confirm first. twilio_send_message and twilio_send_verification send a message or a code to a real person and are billed per message or verification. Before calling them, state recipient, sender, channel and text and wait for the user's yes. twilio_delete_message is installed switched off.

Trial accounts send only to up to five verified numbers (error 21608 otherwise) and only within the sign-up country. On the current trial, an SMS sent through the API may only set to, body and status_callback, and body must name one of Twilio's sample templates (sms_2fa, sms_appointment_reminders, sms_order_confirmation, sms_delivery_updates, sms_customer_support, sms_marketing_promotions, sms_event_notifications, sms_account_alerts, sms_feedback_surveys, sms_internal_alerts); free text needs an upgraded account.

WhatsApp: prefix both numbers with whatsapp: (whatsapp:+4915112345678). For a first test use the WhatsApp Sandbox, which is set up in the legacy Console at https://www.twilio.com/console/sms/whatsapp/sandbox: the person sends join <code> to the sandbox number, then you can send from whatsapp:+14155238886 for three days. Outside the 24 hours after the person last wrote, WhatsApp only delivers approved templates: send them with content_sid (HX...) and content_variables (error 63016 otherwise).

Numbers are E.164: + country code and number without spaces (+4915112345678). twilio_list_phone_numbers shows the numbers that can be used as from; twilio_list_messaging_services the Messaging Services (needed for scheduled messages, schedule_type fixed with send_at).

Delivery status: a new message is queued; read it later with twilio_get_message. failed or undelivered come with an error_code; look it up at https://www.twilio.com/docs/api/errors.

Lookup: twilio_lookup_phone_number without fields is free and checks format and country. Every data package in fields (line_type_intelligence, sms_pumping_risk, caller_name and others) is billed per lookup; ask first.

Verify: create a Verify service once in the Console (Verify, Services, Create new) and use its VA... sid. Each approved verification costs about 0.05 USD plus the channel fee. twilio_send_verification sends the code, twilio_check_verification checks what the person typed (status approved when right).

Paging: list answers carry next_page_uri (null on the last page). For the next page pass page and page_token from that URI. Messages, calls and usage are listed newest first.

Usage and cost: twilio_list_usage_records for a date range, twilio_list_usage_records_by_period per day, month or year or for a window like ThisMonth. Category totalprice is the total spend; twilio_get_balance the remaining balance.

Common errors

• 401 / 20003: wrong SID or secret, or an API key used with a different Account SID than the one it belongs to.
• 404 / 20404: no such message, call, number or service on this account.
• 400 / 21211: invalid to number. 21606: the from number is not a Twilio number of this account or cannot send SMS. 21610: the recipient replied STOP.
• 429 / 20429: too many requests; wait and try again.

Out of scope here: placing calls, buying or configuring numbers, Conversations, Studio, Flex, Voice TwiML and webhooks.