Messages Not Delivered

Message delivery failures are the most commonly reported issue on Sent. This guide walks through every major failure scenario, from API misconfiguration to carrier-level filtering, with concrete steps to resolve each one.

Diagnostic Flowchart

Before reading the full guide, use this decision tree to narrow down the problem:

WhatsApp Messages Fail via API but Work from Dashboard

This is the most commonly reported delivery issue. You send a WhatsApp message through the API, the call returns a 2xx success response, but the message ultimately shows as failed in your Activities log. Meanwhile, sending the exact same template from the Sent dashboard delivers successfully.

Why This Happens

When the API accepts your request, it means the request was syntactically valid and queued. The actual delivery attempt happens asynchronously, and it can fail for reasons the initial response cannot predict. The dashboard works because it builds the payload for you with the correct structure.

Common Causes

1. Missing or incorrect template object

The v3 API requires a template object with either an id or name field. Passing the template ID as a flat string or using the wrong field name will cause the message to fail during processing.

// Incorrect - flat string
{
  "to": ["+1234567890"],
  "template": "tmpl_abc123",
  "channel": "whatsapp"
}

// Correct - template object with id
{
  "to": ["+1234567890"],
  "template": { "id": "tmpl_abc123" },
  "channel": "whatsapp"
}

// Also correct - template object with name
{
  "to": ["+1234567890"],
  "template": { "name": "order_confirmation" },
  "channel": "whatsapp"
}

2. Channel not specified correctly

The channel field must be the lowercase string "whatsapp". Values like "WhatsApp", "WHATSAPP", or "wa" are not recognized and will cause the message to be routed incorrectly or rejected.

3. Recipient does not have WhatsApp

If the recipient's phone number is not registered with WhatsApp, the message cannot be delivered on that channel. The API will accept the request, but delivery will fail. Check the Activities log for a status indicating the number is not WhatsApp-capable.

4. Template parameter mismatch

If your approved template expects three variables but your API request supplies two (or vice versa), the message will fail. Parameter types also matter — sending a string where the template expects a currency or date-time object will cause a rejection from Meta.

How to Debug

1. Open Dashboard → Activities and find the specific message by recipient number or message ID.
2. Check the error details — the Activities log includes the downstream error from Meta or the carrier.
3. Send the same message from the dashboard and compare the payload. The dashboard's outbound payload is visible in the message detail view.
4. Verify your template ID is correct by checking Dashboard → Templates and confirming the template status is Approved.

WhatsApp ERR_ECOSYSTEM_ENGAGEMENT / Error 131049

If you see the error code 131049 or the message ERR_ECOSYSTEM_ENGAGEMENT, this is a restriction imposed by Meta, not by Sent.

What It Means

Meta enforces anti-spam protections on WhatsApp Business messages. Error 131049 typically means one of:

• More than 24 hours have passed since the customer last replied to you, and you are attempting to send a session (free-form) message instead of a pre-approved template.
• WhatsApp is throttling your messages to protect what they call "healthy ecosystem engagement." This happens when Meta's systems detect patterns that resemble spam — high volume sends to recipients who rarely engage, repeated messages to the same number, or low read/reply rates.

Solutions

Respect the 24-hour conversation window. WhatsApp allows free-form session messages only within 24 hours of the customer's last message to you. Outside that window, you must use an approved message template to initiate contact.

Use approved templates to start conversations. If you need to reach out to a customer who has not messaged you recently, always send a template message. Session messages sent outside the window will be rejected with error 131049.

Reduce message frequency. If you are sending multiple messages to the same recipients in a short period, Meta may begin blocking delivery. Space out your sends and ensure each message provides clear value to the recipient.

Check for template reclassification. Meta periodically reviews and reclassifies templates. A template originally approved as Utility may be reclassified to Marketing, which has stricter sending limits. If you believe your template was reclassified incorrectly:

1. Open Meta Business Manager.
2. Navigate to WhatsApp Manager → Message Templates.
3. Find the affected template and submit an appeal for reclassification.

SMS Not Delivered in Specific Countries

SMS delivery relies on carrier agreements that vary by country. A message that delivers instantly in the US may fail or be silently filtered in another region.

Common Patterns

• Carrier-level filtering: Countries including Algeria and several countries in the Middle East and Africa apply aggressive content filtering. Messages may be silently dropped without a delivery failure being reported back to Sent.
• Alphanumeric sender ID restrictions: Some countries do not support alphanumeric sender IDs (e.g., "MySaaS" as the sender name). In these countries, the sender ID may be silently converted to a local number or the message may be blocked entirely.
• Registration requirements: Certain countries require pre-registration of sender IDs or message content before SMS can be delivered. Sending without registration results in filtering.

Solutions

1. Check the Sent coverage page for your target country. The coverage data includes supported sender ID types and known filtering behavior.
2. Try a different sender ID type. If you are using an alphanumeric sender ID, switch to a numeric sender ID (a dedicated phone number) for countries that do not support alphanumeric IDs.
3. Contact Sent support for country-specific routing information. Our team can advise on the best sender type, content guidelines, and any registration requirements for your target country.
4. Monitor delivery rates by country in the Activities dashboard. A sudden drop in delivery rate for a specific country often indicates a carrier policy change.

Messages Routing to Wrong Sender Number

You configured a Sender Profile with a dedicated long code or toll-free number, but messages are still going out from a shared short code.

Cause

The sender_profile_id field is not included in your API request. When this field is omitted, Sent uses the default routing logic, which may select a shared short code based on cost and deliverability optimization.

Solution

Include the sender_profile_id in every message request where you want to control the outbound number:

curl -X POST https://api.sent.dm/v3/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["+1234567890"],
    "template": { "id": "tmpl_xxx" },
    "channel": "sms",
    "sender_profile_id": "sp_xxx"
  }'

You can find your Sender Profile ID in Dashboard → Sender Profiles. Each profile displays its ID (prefixed with sp_), the associated phone number, and the channel it supports.

Sending SMS Only When WhatsApp Is Connected

You have connected a WhatsApp Business Account during onboarding, but you want all messages sent exclusively via SMS — either because you have a separate WhatsApp integration elsewhere, or because you do not want Sent's channel selection logic to attempt WhatsApp delivery.

Why This Happens

By default, when a WhatsApp Business Account is connected to your Sent account, Sent will attempt WhatsApp delivery for recipients with WhatsApp capability. If your architecture already handles WhatsApp through another system, this can cause duplicate delivery attempts or route messages through a channel you are not expecting.

Additionally, if your connected WABA shows as unverified or restricted in Meta Business Manager, this status can affect Sent's channel routing — even if you only need SMS.

Solution

Contact Sent support to enable SMS-only mode on your account. This is a backend configuration that overrides channel selection and forces all outbound messages to route as SMS, regardless of whether a WABA is connected or what status it shows.

Once SMS-only mode is enabled:

• Messages are always delivered via SMS, regardless of WABA connection state
• You do not need to disconnect your WhatsApp Business Account
• WABA verification status has no impact on SMS delivery

WhatsApp-to-SMS Failover Not Triggering

You configured WhatsApp as the primary channel with SMS as the fallback, but every message is being sent via SMS — the WhatsApp attempt never seems to happen.

Common Causes

WhatsApp template not approved. Failover logic evaluates whether the primary channel can deliver before attempting it. If the specified template is not approved for WhatsApp, Sent skips the WhatsApp attempt entirely and falls through to SMS.

WhatsApp Business Account not connected. If your WhatsApp Business Account is disconnected or was never fully set up, Sent cannot send on the WhatsApp channel. Verify your connection status under Dashboard → Channels → WhatsApp.

Recipient number not recognized as WhatsApp-capable. Sent performs a channel capability check before attempting delivery. If the recipient's number is not detected as having WhatsApp, the system will immediately fall back to SMS without attempting WhatsApp delivery.

How to Debug

Open the message in Dashboard → Activities and look for two key fields in the message detail:

• channel_attempted — shows which channel Sent tried first (should be whatsapp if failover is configured correctly).
• fallback_reason — explains why the system fell back to SMS. Common values include template_not_approved, channel_not_connected, and recipient_not_capable.

If channel_attempted shows sms from the start (rather than whatsapp), the failover logic was bypassed, which points to a configuration issue on the WhatsApp side.

Checklist

• Confirm the template is approved for WhatsApp in Dashboard → Templates.
• Confirm WhatsApp Business Account is connected and active in Dashboard → Channels.
• Confirm the recipient's number is a valid mobile number (landlines cannot receive WhatsApp messages).
• Confirm your API request specifies the correct channel priority (e.g., "channel": "whatsapp" with "fallback": "sms").

Invalid or Missing API Key (AUTH_002)

If your API request returns the following error, the API key is either missing, malformed, or no longer valid:

{
  "success": false,
  "error": {
    "code": "AUTH_002",
    "message": "Invalid or missing API key"
  }
}

Solutions

Use the correct header. Sent uses the x-api-key header, not Authorization: Bearer. This is the most common mistake when migrating from other APIs.

# Incorrect
curl -H "Authorization: Bearer YOUR_API_KEY_HERE" https://api.sent.dm/v3/messages

# Correct
curl -H "x-api-key: YOUR_API_KEY_HERE" https://api.sent.dm/v3/messages

Copy the key directly from the dashboard. Navigate to Dashboard → API Keys and use the copy button to avoid transcription errors. Ensure there is no trailing whitespace or newline character — these are invisible but will cause authentication to fail.

Check if the key was regenerated. If someone on your team regenerated the API key, the previous key is immediately invalidated. The Activities log does not record authentication failures, so you will not see the failed request there — only the AUTH_002 response from the API.

Verify the key matches your environment. If you have separate keys for production and sandbox, ensure you are using the correct one for the environment you are targeting.

Sandbox Mode — What Gets Delivered and How to Inspect It

When testing your integration in sandbox mode, messages are not actually delivered to recipients and no credit is consumed. Understanding exactly what does happen helps you write reliable tests.

What sandbox mode does

• The API processes the request and returns a success response with a real message ID — identical to a live send.
• The message and its status appear in Dashboard → Activities.
• Webhooks fire with status updates, just as they would in production.
• No SMS or WhatsApp message is sent to the recipient's device.

Pass "sandbox": true in your send request to enable it:

{
  "to": ["+1234567890"],
  "template": { "id": "tmpl_abc123" },
  "channel": "sms",
  "sandbox": true
}

Retrieving template variables (e.g. OTP codes) in sandbox

A common testing scenario is verifying that your OTP or other variable-content template was constructed correctly, without needing to receive a real message. You can do this by calling the get-message-status endpoint with the message ID returned from the send call. The response includes the template variables submitted with that message — so you can confirm the correct code or value was passed.

GET /v3/messages/{message_id}

This works in sandbox mode. The message ID in the send response is real and queryable.

When to switch to live mode

Use sandbox for all logic testing: template variable substitution, webhook handling, status polling, and error path coverage. Switch to live mode only when you need to verify the actual end-to-end recipient experience — for example, confirming that an OTP code renders correctly on a specific device or carrier.

Still Not Resolved?

If none of the scenarios above match your issue:

1. Collect your diagnostic information: message ID, timestamp, recipient number (redacted if needed), the exact API request payload (with sensitive values replaced), and the full error response.
2. Check the Sent status page for any ongoing incidents that could affect delivery.
3. Contact support at support with the information from step 1. Including these details upfront significantly reduces resolution time.

Related Guides

• WhatsApp Template Issues — if messages fail due to template approval, categorization, or parameter problems
• Phone Number & Sender ID Issues — if messages are sending from the wrong number or you need a different sender ID
• Compliance & 10DLC Issues — if SMS delivery is blocked by carrier restrictions or 10DLC registration issues