Module summary

corvus_sms_inbound turns the dynamic outbound gateway supplied by eis_sms_apis into a two-way messaging system. Each gateway receives a tokenized inbound URL. Provider payload fields are mapped in the gateway form, the receiving number is matched to a gateway-number record, and a routing policy decides whether the reply belongs on the last outbound document, a CRM lead, a contact, or an SMS Inbox thread.

The module also keeps a permanent inbound log, detects duplicate callbacks, supports optional HMAC signature verification, processes delivery-status events, and preserves the sender-number identity used for outbound replies.

Dependencies and prerequisites

Install these Odoo applications before this module:

• eis_sms_apis — the published Corvus dynamic outbound gateway foundation.
• mail — chatter, notifications and bus services.
• crm — lead routing and SMS-thread ownership.
• web — backend views and client services.

You also need an account with an SMS provider, a provider-owned sending/receiving number, and an HTTPS Odoo address reachable by that provider. Provider charges, number rental, registration and telecom compliance are external to this module.

Installing Corvus SMS Inbound

1. Place corvus_sms_inbound in the same addons path.
2. Update the Apps list.
3. Search for Corvus SMS Inbound and click Install.
4. Open Settings and confirm that the SMS Routing application section is available.
5. Open the SMS gateway list and confirm that Numbers, Inbound and Guide pages are available on a gateway form.

New menus, views and objects

The module adds or extends these working areas:

• Settings > SMS Routing for routing, inbox and fallback-sender policy.
• SMS Gateways with inbound capability, callback, mapping, security and gateway-number controls.
• SMS Inbox under Discuss for conversation threads that should not be lost when no business document can be selected safely.
• Inbound SMS Logs for payload, headers, duplicate evidence and processing results.
• Inbound Parser Test from the gateway form for dry-run payload mapping.
• User and company forms for allowed and default gateway numbers.
• CRM lead forms with the SMS Thread ownership option.

Configure the routing policy

Open Settings, locate SMS Routing, and decide what the system should do before you expose the webhook to a provider.

1. Set Primary Target:
   • Last Outbound continues the conversation on the document that most recently sent SMS to this number.
   • CRM Lead selects a lead belonging to the matched contact.
   • Contact posts on the contact chatter.
   • SMS Inbox keeps the conversation in its dedicated inbox thread.
2. Set a Fallback Target for cases where the primary target cannot be found.
3. If CRM is used, select the lead strategy: latest lead, the lead marked as the SMS thread, or the lead found from the last outbound SMS.
4. Configure the actions for a missing last outbound message, missing lead and missing contact. Each condition can use the fallback, create an appropriate record where supported, use SMS Inbox, or discard the event.
5. Decide whether unlinked inboxes are allowed. If not, choose whether Odoo creates a contact or discards the unmatched message.
6. Optionally set the global fallback sender number used when user and company defaults do not resolve one.
7. Save Settings.

Configure an inbound gateway

Open SMS Gateways, remove the default Active filter if you need to review all built-in templates, then open the gateway that will receive live traffic.

Webhook security

The random URL token is the minimum identification mechanism. If your provider supports signed callbacks, enable signature verification and configure:

• signature header name;
• secret shared with the provider;
• HMAC algorithm and optional prefix;
• whether the raw body or another payload representation is signed;
• timestamp header and maximum accepted age, when supplied by the provider.

Keep tokens and secrets out of screenshots, tickets and public documentation. Signature settings must match the provider byte-for-byte; an incorrect payload mode is a common cause of valid callbacks being rejected.

Configure multiple gateway numbers

The Numbers page is both the inbound receiving-number registry and the outbound sender-number policy.

For each provider number:

1. Enter a clear label that operators will recognize in chatter and composers.
2. Enter the provider number and verify its normalized value.
3. Choose a display color to distinguish number tabs and message context.
4. Set sequence and active state.
5. Mark one default number per gateway when appropriate.
6. Restrict Allowed Users if the number belongs to a team or region.
7. Add country prefixes when the number should be preferred for matching destinations in specific countries.
8. Configure hourly or daily limits when sender-number throttling is required.

The effective outbound default is resolved from the user default, company default, global default, and then the first eligible active number. Limits and user access are checked before the number is used.

Test payload mapping before go-live

Use Test Inbound Parser from the gateway form. This tool parses sample data without requiring a provider to send a real message.

1. Paste a representative JSON payload supplied by the provider.
2. Paste representative headers when testing signature or header-dependent behavior. Never paste a production secret into shared documentation.
3. Run the parser preview.
4. Confirm sender, recipient, body, message ID, event type and gateway number.
5. Check whether the test would match an existing duplicate.
6. Correct gateway paths and repeat until every extracted value is accurate.

Do not activate a production webhook while the receiving number or body parses as empty. A successful HTTP response alone does not prove correct routing.

How an inbound SMS is processed

When the provider calls the tokenized route, Odoo follows this sequence:

1. Identify candidate gateways from the token.
2. merge query, form, JSON or raw-body values;
3. classify the event as inbound SMS or delivery status;
4. verify the optional HMAC signature;
5. compute a duplicate key and compare it with recent logs;
6. match the receiving number to sms.gateway.number;
7. normalize the sender and find a contact;
8. apply the configured primary and fallback routing policy;
9. post the message to the selected chatter and maintain SMS Inbox continuity;
10. create inbound sms.sms and mail.notification records;
11. send bus events so installed suite interfaces can refresh; and
12. mark the inbound log as processed or record a useful error.

SMS Inbox

SMS Inbox is the safe conversation fallback. It stores one thread per normalized phone identity, links a contact when available, tracks total and unread counts, and records the latest message.

Open a thread to read its chatter history. The base module supplies inbox records and unread state; companion modules add richer chatter tabs, floating chat, desktop alerts and email notifications.

Inbound logs and diagnostics

Open Inbound SMS Logs when a callback is missing, duplicated or routed to an unexpected destination.

Review:

• gateway and raw sender/recipient values;
• provider message and webhook event IDs;
• payload and header snapshots;
• received, processed or error status;
• duplicate flag and original log reference; and
• processing note explaining the selected route or failure.

Use the log search filters to separate processed, duplicate and error traffic. Open the duplicate reference to compare the replay with the original event; open error records to read the payload and processing note together.

Inbound and outbound messages in chatter

Inbound records use direction inbound and state received. Outbound records retain their normal sending/delivery states. The associated gateway number is written to SMS and chatter metadata, allowing companion interfaces to show the receiving/sending identity and separate customer replies from staff messages.

Delivery-status callbacks

Status events locate the existing status record through the provider message ID and gateway. The handler then updates sms.status, the linked tracker and the linked sms.sms state. If inbound and status traffic share one callback URL, the configured discriminator must classify both event types reliably.

Security and access

Administrators manage gateways, logs, parser tests and number policy. Internal users can work with SMS Inbox and read gateway numbers according to access. A number's Allowed Users list further controls who can select it for outbound work. Treat the public webhook as an internet-facing integration: use HTTPS, rotate exposed tokens, enable provider signatures where possible, and retain logs according to your privacy policy.

Troubleshooting

Provider receives 404 or gateway is not found

Copy the current callback URL again. Confirm that the token belongs to an active gateway and that the public hostname reaches this Odoo database.

Log exists but sender, recipient or body is blank

The payload path is wrong. Paste the same payload into the parser and map the nested provider field exactly.

Signature validation fails

Compare header name, algorithm, prefix, secret, payload mode and timestamp tolerance with the provider's signing documentation.

A callback is marked duplicate

Check provider event/message IDs and the idempotency window. Replayed events are intentionally suppressed when they produce the same deduplication key.

Message routed to the wrong record

Review the primary target, lead strategy, missing-target actions, last outbound history, contact phone normalization and receiving-number match.

Users cannot select a sender number

Check active state, allowed users, quota counters, and user/company/global defaults.

Limitations and provider responsibility

Gateway APIs and webhook formats differ. Custom gateways are not guaranteed to work without adjustment. Telnyx and LoopMessage have been tested for inbound and outbound SMS/MMS workflows, but Corvus Nexus Technologies LTD is not an official partner, reseller or telecom provider for them or any other SMS provider.

Odoo IAP inbound support is not provided by this module. Inbound SMS (and MMS inbound) requires a third-party SMS/MMS provider that supports inbound webhooks/callbacks, plus an active inbound-enabled package and valid provider balance/credits on that gateway. MMS inbound is also only available through compatible third-party gateway setups, never through Odoo IAP.

After purchase, Corvus Nexus Technologies LTD can assist with configuring one specific gateway without an additional service charge. This does not include provider fees, custom development, number procurement, telecom compliance work or a guarantee of third-party delivery.

Related modules in the suite

• eis_sms_apis — dynamic outbound gateway foundation.
• corvus_mms_base — inbound/outbound media and expiring public media links.
• corvus_sms_workspace — chatter composer, sender selection and soft delete.
• corvus_sms_chatter_tabs — per-number tabs, private notes, AI and rerouting.
• corvus_sms_floating_chat — always-available inbox panel.
• corvus_sms_suite — systray, sound, desktop/email alerts and transcription.
• corvus_sms_translation and corvus_sms_loop_lookup — optional language and device-intelligence enhancements.
• corvus_sms_blaster — optional campaign workflow.

Professional Services

Corvus Nexus Technologies LTD provides Odoo SMS/MMS implementation, gateway and webhook setup, provider mapping, custom integration, version/data migration, deployment support, team training, troubleshooting and ongoing optimization.

Support and Contact