SMS Gateway & API Routing
Purpose
SMS Gateway & API Routing connects Odoo's SMS sending flow to configurable HTTP gateways. An administrator describes the provider request, chooses routing rules, and maps responses. The module is the foundation for provider adapters and the two-way messaging modules; it does not itself provide a conversation inbox.
Before you start
Install the package for your exact Odoo major version with its sms dependency. The manifest declares no Enterprise-only dependency. An external provider must already supply the permitted sender, endpoint and authentication requirements before an administrator configures live sending. This guide covers the 19.0 source; no installation, provider delivery or runtime test was performed.
Access and roles
The module gives Settings administrators (base.group_system) full access to gateway, parameter, header, callback-mapping and status records. It adds no general internal-user gateway ACL. An administrator should establish the intended sending user's access with the installed companion modules before enabling production use. Do not share screenshots containing credentials, callback tokens or raw provider responses.
Setup and menu
Open SMS Gateways under the phone/SMS configuration menu. Create a gateway and configure these tabs:
| Tab | Fields and purpose |
|---|---|
| API Settings | Base URL, HTTP Method (GET or POST), Request Type (Form Data or JSON), Priority, Country Prefix, and optional multiple-recipient handling. Lower priority numbers are considered first. |
| Authentication | Authentication Type, API Key, Token, Username, Password. Basic Auth supplies HTTP Basic authentication; API keys and tokens must also be placed in the appropriate parameter, header or JSON field. |
| Parameters / Headers | Set each provider key and its value. {phone}, {phones}, {message}, {api_key}, {token}, {username} and {password} are supported substitutions. |
| JSON Body | Supply the provider's JSON structure. Typed tokens such as __phones_list__ preserve an array value where needed. |
| API Settings / Status | Configure Success HTTP Codes, Success Substring, Message ID Regex, Success Key, Error Key and Track Status according to the response format. |
In Settings, Use IAP bypasses custom gateways entirely. SMS Gateway chooses the default. Fallback to IAP? applies to recipients for which no gateway was selected; it is not a retry mechanism for a provider that returned an error.
Workflow
- Save the gateway in New state while completing its request definition. Review Request Preview to catch missing keys and incorrect structure. The preview is not a provider connectivity test.
- Define country prefixes such as
+1,+44, and set priority deliberately when routes overlap. The routing code selects the first matching active gateway by priority, then the configured default, then the first active gateway. It does not select the longest matching prefix. - Use Toggle State to activate a completed configuration. Keep the archive flag and state consistent; prefix routing requires an unarchived gateway in Active state. Ensure a configured default remains appropriate, because the default lookup is not subjected to the same active-state search.
- From an authorised Odoo SMS workflow, prepare the recipient and message. A real send makes an external HTTP request and may incur provider charges. Use only an approved provider test arrangement for a connectivity check.
- Review Total SMS, Sent SMS, Failed SMS and stored statuses when tracking is enabled. An immediate HTTP success reports request acceptance; it is not independent evidence that a handset received the message.
- If delivery reports are required, enable Delivery Callback Enabled and map UUID Param, Message ID Param, Status Param, error fields and comma-separated success/pending/error/canceled values. Prefer UUID correlation. Otherwise capture the provider ID with Message ID Regex or a recognised response ID.
The Callback URL uses /eis_sms/callback/<token>. It accepts public GET/POST requests using the token to locate the gateway, without a signed-request check in this base controller. Treat the URL as a secret and restrict its distribution to the intended provider. A matching token and an “OK” response alone do not establish that a tracker was found or updated.
Practice scenario
In an authorised training database, draft a Training Route with https://example.invalid/messages, POST JSON, prefix +1, and a body containing a fictional recipient +12025550123 and “Your sample collection is ready.” Leave the route in New and inspect its preview without sending. Add a second draft route with a lower priority number to discuss which route would win if both matched. This exercise is source-derived and was not executed.
Troubleshooting and limitations
No matching SMS gateway configured means no gateway was selected and IAP fallback was disabled. A request-building error points to the endpoint or template; connection, timeout and HTTP failures appear as server errors. Do not immediately resend after a timeout until provider status is reconciled, because the original request may have been accepted.
Explicit Error Key matches take precedence over success indicators. Missing callback correlation leaves delivery status unresolved. Multiple-recipient mode uses the first recipient's UUID as the request reference, so confirm how the provider reports individual deliveries before relying on per-recipient callback results. Credentials are ordinary configured field values with masked form widgets; masking is not a separate secret vault.
Versions and useful links
Catalogue packages exist for 16.0–20.0. The 19.0 workflow is source-reviewed. Selected comparisons show 17.0 uses tree-style lists, 18.0 largely shares the reviewed implementation, and 20.0 changes framework access declarations, configuration reads and archive controls. The 16.0 source differs substantially and lacks the reviewed delivery-callback controls; this workflow must not be assumed equivalent there.
Choose the exact version in the Corvus app catalogue, including its available Live Test selector. Direct demo reachability was not confirmed and no demo was launched. Continue with Two-Way SMS & CRM Inbox, Twilio SMS Gateway or MMS Media & Attachments as required.