.. container:: .. container:: header .. rubric:: Dynamic SMS Gateway User Guide :name: dynamic-sms-gateway-user-guide Your Complete Guide to Sending SMS Messages with Odoo .. container:: toc section .. rubric:: Table of Contents :name: table-of-contents - `1. Introduction <#introduction>`__ - `2. Getting Started <#getting-started>`__ - `3. Module Overview <#module-overview>`__ - `4. Configuring Settings (res.config.settings) <#settings>`__ - `5. Understanding SMS Gateways <#gateways>`__ - `6. How Gateways Are Selected for a Number <#gateway-selection>`__ - `7. Using Gateway Templates <#using-templates>`__ - `8. Creating a New Gateway <#creating-gateways>`__ - `9. Parsing SMS Responses <#response-parsing>`__ - `10. Troubleshooting <#troubleshooting>`__ - `11. Best Practices <#best-practices>`__ .. container:: section :name: introduction .. rubric:: 1. Introduction Welcome to the **Dynamic SMS Gateway (eis_sms_apis)** module for Odoo! This powerful tool lets you send SMS messages directly from Odoo using your favorite providers—like Twilio, SendPK, or MSG91—without needing to be a tech expert. Designed for non-developers, this guide walks you through every step, from setup to sending messages, ensuring you can communicate with customers worldwide affordably and efficiently. **Why Use This Module?** Odoo’s default SMS service (called IAP) can be expensive, especially outside the EU. Our module connects to local or global SMS providers, often at lower rates, and gives you full control over how messages are sent. Whether you’re in India, KSA, or the UK, we’ve got you covered with pre-built templates and easy customization. .. container:: alert alert-info **Who’s This For?** You! The business owner, marketer, or admin who wants to send SMS without coding. Developers can tweak it, but this guide keeps it simple for everyone else. .. container:: section :name: getting-started .. rubric:: 2. Getting Started .. rubric:: What You’ll Need :name: what-youll-need - **Odoo:** Version 18 or compatible, installed and running. - **Dynamic SMS Gateway Module:** Installed by your Odoo admin (ask them if it’s not there). - **SMS Provider Account:** Sign up with a provider (e.g., Twilio, Fast2SMS) and get your credentials (API key, token, etc.). - **Odoo Access:** You need to be a system user to access it. **Settings > Technical > SMS / Phone > SMS Gateways** and **Technical > System Parameters**. .. rubric:: Installation :name: installation Your Odoo administrator will install the module via the Apps menu. Once done, you’ll see: - **SMS Gateways:** Under **Settings > Technical > SMS / Phone > SMS Gateways**, listing pre-built gateways. ``You may need to activate Developers Tools`` - **Settings Options:** In **Settings > General Settings** , under "Contacts". **First Look:** Open **SMS Gateways** to see templates like "Twilio (USA)" or "SendPK (Pakistan)". These are ready to customize! .. container:: section :name: module-overview .. rubric:: 3. Module Overview The Dynamic SMS Gateway module replaces Odoo’s default SMS sending system with a flexible setup using **SMS Gateways**. Here’s how it works: - **Gateways:** Bridges between Odoo and SMS providers (e.g., Twilio). - **Templates:** Pre-built setups for 37 providers, ready to tweak. - **Settings:** Control when to use gateways or Odoo’s IAP. - **Status Tracking:** See if messages were sent successfully. When you send an SMS (e.g., from a Contact), Odoo checks these settings and gateways to decide how to send it. Let’s dive into each part! .. container:: section :name: settings .. rubric:: 4. Configuring Settings (res.config.settings) :name: configuring-settings-res.config.settings The **SMS Configuration** section in **Settings > General Settings > Contact** controls how Odoo sends SMS. These settings are stored in **res.config.settings** and decide whether to use gateways or Odoo’s IAP. .. rubric:: Settings and Their Roles :name: settings-and-their-roles +-----------------------+-----------------------+-----------------------+ | Setting | What It Does | When It’s Used | +=======================+=======================+=======================+ | **Use IAP | If checked ("True"), | - **Checked:** All | | (sms.use_iap)** | Odoo uses its default | SMS go via IAP, | | | IAP service instead | ignoring gateways. | | | of gateways. | - **Unchecked:** | | | | Gateways are used | | | | based on number | | | | prefixes or | | | | defaults. | +-----------------------+-----------------------+-----------------------+ | **IAP Fallback | If checked ("True"), | - **Checked:** If no | | (sms.iap_fallback)** | Odoo falls back to | gateway is found, | | | IAP when no gateway | IAP sends the SMS. | | | matches a number. | - **Unchecked:** SMS | | | | fails if no gateway | | | | matches. | +-----------------------+-----------------------+-----------------------+ | **Default Gateway | Sets a fallback | - **Set:** Used when | | ( | gateway if no prefix | no gateway’s prefix | | sms.sms_gateway_id)** | matches. | matches the number. | | | | - **Not Set:** Picks | | | | the first active | | | | gateway or fails if | | | | none exist. | +-----------------------+-----------------------+-----------------------+ .. rubric:: How to Configure :name: how-to-configure #. Go to **Settings > General Settings**. #. Scroll to **Contacts**. #. **Use IAP:** Check if you want Odoo’s default service; uncheck to use gateways. #. **IAP Fallback:** Check to ensure SMS still sends via IAP if gateways fail. #. **Default Gateway:** Select a gateway (e.g., "Twilio") from the dropdown. #. Click **Save**. .. rubric:: When IAP vs. Gateway Is Used :name: when-iap-vs.-gateway-is-used - **IAP Used:** If **Use IAP** is checked, all SMS go through Odoo’s service, bypassing gateways. - **Gateway Used:** If **Use IAP** is unchecked, Odoo picks a gateway (see next section). - **Fallback:** If no gateway matches and **IAP Fallback** is on, IAP kicks in. .. container:: alert alert-tip **Tip:** Uncheck **Use IAP** and set a **Default Gateway** for cost savings with local providers! .. container:: section :name: gateway-selection .. rubric:: 6. How Gateways Are Selected for a Number :name: how-gateways-are-selected-for-a-number When you send an SMS, Odoo decides which gateway to use based on the phone number. Here’s the exact process: .. rubric:: Step-by-Step Selection Logic :name: step-by-step-selection-logic #. **Check Settings:** If **Use IAP** is checked, Odoo skips gateways and uses IAP. #. **Get Active Gateways:** - Odoo looks for gateways where: - **Field Active:** Checkbox is ticked. - **State:** Set to "Active" (not "New" or "Disabled"). - This gives a list of usable gateways. #. **Match Prefix:** - Odoo cleans the phone number (e.g., "+923001234567" becomes "923001234567"). - It checks each gateway’s **Country Prefixes** (e.g., "+92,+9230"). - If a prefix matches (e.g., "9230" matches "923001234567"), that gateway is a candidate. #. **Pick Lowest Sequence:** - If multiple gateways match, Odoo picks the one with the lowest **Sequence** number (e.g., 10 beats 20). #. **Default Gateway:** - If no prefix matches, Odoo uses the **Default Gateway** from settings (e.g., "Twilio"). #. **First Active Gateway:** - If no prefix matches and no default is set, Odoo picks the first gateway from the active list (lowest sequence). #. **No Gateway:** - If no gateways are active or match, and **IAP Fallback** is on, IAP is used. Otherwise, the SMS fails. .. rubric:: Example :name: example Phone number: ``+923001234567`` - **Gateways:** - "SendPK" (Active, State: Active, Prefix: "+92,+9230", Sequence: 10) - "SMS Country PK" (Active, State: Active, Prefix: "+92", Sequence: 20) - "Twilio" (Active, State: Active, No Prefix, Sequence: 30, Default Gateway) - **Process:** - Both "SendPK" and "SMS Country PK" match "+9230". - "SendPK" (Sequence: 10) wins over "SMS Country PK" (Sequence: 20). - **Result:** "SendPK" sends the SMS. .. container:: alert alert-tip **Tip:** Set **Country Prefixes** and tweak **Sequence** to control which gateway handles specific numbers! .. container:: section :name: using-templates .. rubric:: 7. Using Gateway Templates :name: using-gateway-templates We’ve included over 37 pre-built gateway templates for providers like Twilio, SendPK, and Fast2SMS. These are ready-to-use setups based on real documentation, but they need your personal touch. .. rubric:: Step-by-Step :name: step-by-step #. **Find Templates:** Go to **Settings > Technical > SMS / Phone > SMS Gateways**. ``You need to enable developer mode.`` #. **Pick One:** See names like "Twilio (USA)" or "Msegat (KSA)". Click one. #. **Update Credentials:** - Look for ``demo`` in **API Key**, **Token**, **Username**, or **Password**. - Replace with your real details from the provider (e.g., Twilio’s Account SID and Auth Token). #. **Set Sender:** In **Parameters**, find "From" or "sender" and replace "[Your Sender ID]" with your registered number or ID. #. **Activate:** - Tick **Active**. - Click **Toggle State** until **State** is "Active". #. **Save:** Hit **Save**. #. **Test:** Send a test SMS from a Contact or the SMS Composer. .. rubric:: About Templates :name: about-templates - **Source:** Created from official provider documentation. - **Demo Data:** Fields like **API Key** are set to "demo"—replace them! - **Not Tested:** We haven’t tested these live; verify with the **Gateway Documentation Link** for updates. .. container:: alert alert-warning **Warning:** Providers may update their APIs. Always check the documentation link and test before bulk sending! .. container:: section :name: creating-gateways .. rubric:: 8. Creating a New Gateway :name: creating-a-new-gateway Need a provider not in our templates? Create your own gateway with these steps. .. rubric:: Step-by-Step :name: step-by-step-1 #. **Start Fresh:** **Settings > Technical > SMS / Phone > SMS Gateways > Create**. #. **Basic Info:** - **Name:** E.g., "My SMS Provider". - **Base URL:** From provider docs (e.g., ``https://api.mysms.com/send``). - **Method:** "GET" (simple URL) or "POST" (data sent in body). - **Request Type:** "Form Data" (key-value pairs) or "JSON" (structured data). #. **Authentication:** - **Type:** "None", "API Key", "Token", "Basic Auth", or "Custom". - **API Key/Token:** Enter your key/token. - **Basic Auth:** Add **Username** and **Password**. #. **Parameters:** Add under **Parameters**: - **Key:** E.g., "to", "message". - **Value:** Use placeholders like ``{phone}``, ``{message}``. - **Type:** "Single Number", "Multiple Numbers", "Message", "Authentication", or "Other". #. **Headers:** Add under **Headers** if needed (e.g., ``Key: Authorization``, ``Value: Bearer {token}``). #. **JSON Body:** For "POST" with "JSON", enter a template (e.g., ``{"to": "{phone}", "text": "{message}"}``). #. **Success Settings:** - **Success HTTP Codes:** E.g., "200,201". - **Success Substring:** E.g., "success". - **Message ID Regex:** E.g., ``"id":"([A-Za-z0-9]+)"``. #. **Save and Activate:** Save, tick **Active**, set **State** to "Active". .. rubric:: Field Roles :name: field-roles +----------------+-------------------------+-------------------------+ | Field | Role | Example | +================+=========================+=========================+ | **Parameters** | Data sent to the | ``Ke | | | provider (e.g., phone | y: to, Value: {phone}`` | | | number, message). | | +----------------+-------------------------+-------------------------+ | **Headers** | Extra info sent with | ``Key: Authorization, | | | the request (e.g., | Value: Bearer {token}`` | | | authentication). | | +----------------+-------------------------+-------------------------+ | **JSON Body** | Structured data for | ``{"to": "{phone}", | | | "POST" with "JSON" | "text": "{message}"}`` | | | (replaces parameters). | | +----------------+-------------------------+-------------------------+ .. rubric:: HTTP Methods and Types :name: http-methods-and-types - **GET:** Simple request via URL (e.g., ``api.com/send?to={phone}``). - **POST:** Sends data in the body, more secure. - **Form Data:** Key-value pairs (e.g., ``to={phone}&message={message}``). - **JSON:** Structured data (e.g., ``{"to": "{phone}"}``). .. rubric:: Placeholders :name: placeholders Placeholders are special tags replaced when sending SMS: - ``{phone}``: Single phone number (e.g., "+923001234567"). - ``{phones}``: Multiple numbers (e.g., "+92300,+92301"). - ``{message}``: The SMS text (e.g., "Hello!"). - ``{api_key}``, ``{token}``, ``{username}``, ``{password}``: Your credentials. **How It Works:** Odoo swaps these with real values (e.g., ``{phone}`` becomes "+92300…"). URLs, parameters, headers, and JSON bodies use these placeholders. .. container:: section :name: response-parsing .. rubric:: 9. Parsing SMS Responses :name: parsing-sms-responses After sending an SMS, the provider replies with a response (e.g., "success" or an error). Odoo uses these fields to understand it: .. rubric:: Key Fields :name: key-fields +----------------------+----------------------+----------------------+ | Field | Purpose | Example | +======================+======================+======================+ | **Track Status** | If checked, logs | Check to see | | | responses in **SMS | results. | | | Statuses**. | | +----------------------+----------------------+----------------------+ | **Success HTTP | Codes meaning | ``200,201`` | | Codes** | "success". | | +----------------------+----------------------+----------------------+ | **Success | Text in the response | ``OK``, ``sid`` | | Substring** | showing success. | | +----------------------+----------------------+----------------------+ | **Message ID Regex** | Pattern to extract a | ``"id | | | tracking ID. | ":"([A-Za-z0-9]+)"`` | +----------------------+----------------------+----------------------+ .. rubric:: How Responses Are Parsed :name: how-responses-are-parsed Example Response: ``{"sid": "SM123", "status": "sent"}`` - **HTTP Code:** If "201" is in **Success HTTP Codes**, it’s a success. - **Substring:** If "sent" matches **Success Substring**, it’s a success. - **Message ID:** ``"sid":"([A-Za-z0-9]+)"`` grabs "SM123". - **Result:** Marked "Success" in **SMS Statuses**. .. rubric:: Tips :name: tips - Enable **Track Status** to see raw responses. - Test with a sample SMS to find the right codes and substrings. - Use regex tools to build **Message ID Regex**. .. container:: section :name: troubleshooting .. rubric:: 10. Troubleshooting - **SMS Not Sending:** - Is **Use IAP** checked? Uncheck it. - Gateway not **Active** or "Active" state? - Credentials still ``demo``? - Prefix mismatch? - **Wrong Status:** Adjust **Success HTTP Codes** or **Success Substring**. - **No ID:** Check **Message ID Regex** against the response. .. container:: section :name: best-practices .. rubric:: 11. Best Practices - Set **Sequence** low for preferred providers. - Use **Country Prefixes** for regional targeting. - Test every gateway with a single SMS first. - Update templates with current provider info. - Enable **IAP Fallback** as a safety net. Start Sending SMS Now!