Send Direct Send WhatsApp Utility Messages

This API enables you to send business-initiated WhatsApp utility messages without creating and approving a message template first. WhatsApp automatically generates and manages the template, classifies it, and matches future sends against it.

Direct Send uses the same POST /v1/send endpoint as transactional WhatsApp messages. You do not need to create a separate integration. To use Direct Send, add the category field to the message object.

Unlike free-form WhatsApp text messages, Direct Send messages are business-initiated. The user does not need to have messaged your WhatsApp number within the previous 24 hours.

Direct Send for Utility must be enabled for your account and WhatsApp Business Account before you can use it. To request enablement, contact Insider One team.

Endpoint and Headers

POST https://whatsapp.useinsider.com/v1/send

Body Parameters

The category and ttl_seconds parameters are not validated when the request is received. An invalid category, such as marketing, or a ttl_seconds value outside the supported range can initially return a 200 response. Meta rejects the message afterwards.

The failure is reported asynchronously as a dropped message with WhatsApp error code 100 in the status callback, rather than as an HTTP error. Validate both values before sending the request.

preview_url is not supported for Direct Send messages. URL previews do not apply to auto-generated Utility templates.

Sample Requests

Text message

curl --location 'https://whatsapp.useinsider.com/v1/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.**************************' \
--data '{
   "messages": [
       {
           "phoneNumber": "+1**********",
           "message": {
               "type": "text",
               "text": {
                   "body": "Your order has shipped"
               },
               "category": "utility",
               "ttl_seconds": 600
           }
       }
   ]
}'

Interactive message with reply buttons

You can add up to 3 reply buttons. Button titles can contain up to 20 characters. If you include a header, it must be a text header.

curl --location 'https://whatsapp.useinsider.com/v1/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.**************************' \
--data '{
   "messages": [
       {
           "phoneNumber": "+1**********",
           "message": {
               "type": "interactive",
               "interactive": {
                   "type": "button",
                   "header": {
                       "type": "text",
                       "text": "Header"
                   },
                   "body": {
                       "text": "Pick an option"
                   },
                   "footer": {
                       "text": "Footer"
                   },
                   "action": {
                       "buttons": [
                           {
                               "type": "reply",
                               "reply": {
                                   "id": "qr_1",
                                   "title": "Yes"
                               }
                           },
                           {
                               "type": "reply",
                               "reply": {
                                   "id": "qr_2",
                                   "title": "No"
                               }
                           }
                       ]
                   }
               },
               "category": "utility",
               "ttl_seconds": 3600
           }
       }
   ]
}'

Interactive message with a CTA URL button

You can add exactly 1 CTA URL button. If you include a header, it must be a text header.

curl --location 'https://whatsapp.useinsider.com/v1/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.**************************' \
--data '{
   "messages": [
       {
           "phoneNumber": "+1**********",
           "message": {
               "type": "interactive",
               "interactive": {
                   "type": "cta_url",
                   "body": {
                       "text": "Track your order"
                   },
                   "action": {
                       "name": "cta_url",
                       "parameters": {
                           "display_text": "Track",
                           "url": "https://example.com/track"
                       }
                   }
               },
               "category": "utility",
               "ttl_seconds": 1800
           }
       }
   ]
}'

Combining CTA and Quick Reply buttons

Combining buttons works in this API, subject to its own maximum button rules.

curl --location 'https://whatsapp.useinsider.com/v1/send' \
  --header 'Content-Type: application/json' \
  --header 'x-ins-auth-key: INS.**************************' \
  --data '{
    "messages": [
      {
        "phoneNumber": "+1**********",
        "message": {
          "type": "interactive",
          "interactive": {
            "type": "button",
            "body": {
              "text": "Track your order"
            },
            "action": {
              "buttons": [
                {
                  "type": "cta_url",
                  "parameters": {
                    "display_text": "Track",
                    "url": "https://x.test/track/123"
                  }
                },
                {
                  "type": "reply",
                  "reply": {
                    "id": "1",
                    "title": "Thanks"
                  }
                },
                {
                  "type": "reply",
                  "reply": {
                    "id": "2",
                    "title": "I have an issue"
                  }
                }
              ]
            }
          },
          "category": "utility",
          "ttl_seconds": 3600
        }
      }
    ]
  }'

Sample Responses

The response returns one key for each message in the request, in the same order.

{
    "keys": [
        "whatsapp-*************************"
    ]
}

A 200 response means that the message was accepted for sending. It does not mean that the message was delivered.

401 Unauthorized

{
    "message": "unauthorized"
}

If the x-ins-auth-key header is missing entirely, the API returns:

{
    "message": "authentication required",
    "errorCode": "1001"
}

429 Rate Limit

{
    "message": "rate limited"
}

400 Bad Request

A 400 response is returned when the message is rejected before it is queued. The detail field contains the reason for the failure.

Direct Send is not enabled for the account:

{
    "message": "Message could not be sent. ",
    "detail": "direct send is not enabled for this partner",
    "errorCode": "2003",
    "error": {
        "message": "Message could not be sent.",
        "code": 2003
    }
}

Direct Send is blocked by an active misuse restriction:

{
    "message": "Message could not be sent. ",
    "detail": "direct send is blocked by an active misuse restriction",
    "errorCode": "2003",
    "error": {
        "message": "Message could not be sent.",
        "code": 2003
    }
}

Field validation failure:

This response can occur when a required field such as phoneNumber or message.type is missing.

{
    "message": "failed to validate request",
    "errorCode": "2002",
    "errors": "failed to validate request. | ErrorCode: 2002 | ...",
    "error": {
        "message": "failed to validate request",
        "code": 2002
    }
}

A malformed request body that cannot be parsed returns the same response structure with error code 2001.

403 Forbidden

A 403 Forbidden response occurs when the request is blocked by Cloudflare security mechanisms, which provide an additional protection layer for Insider One infrastructure.

For an IP restriction, the API returns:

{
    "message": "ip-restricted",
    "error": {
        "message": "ip-restricted",
        "code": 1088
    }
}

Warning: A 403 response on this endpoint indicates an IP restriction. Error code 1088 is specific to IP restriction errors.

Direct Send enablement and misuse restriction errors return a 400 response with error code 2003.

Troubleshoot 403 Forbidden errors

If you receive a 403 Forbidden response when making API requests, check the following:

• Verify the User-Agent header usage.

• Review blocked requests in the Cloudflare dashboard.

Category misuse and account restrictions

WhatsApp verifies that content sent through Direct Send for Utility qualifies as utility content. Use Direct Send only for transactional and account-related messages that users expect to receive, such as order and shipping updates, appointment reminders, account and payment alerts, and service notifications.

Promotional and marketing content must be sent using an approved Marketing template.

Repeated category misuse can result in the following enforcement stages:

While a restriction is active, Direct Send messages are rejected with a 400 response and error code 2003. Standard template-based sending is not affected.

No restriction is enforced while a review or appeal is in progress. To dispute a warning or restriction, contact your Insider Customer Success Manager or submit a support request. Stage 4 permanent removal cannot be appealed.

Stage 2 and Stage 3 restrictions are removed automatically when the restriction period expires.

Limitations

• All functions must be executed with an HTTPS POST request.

• This API can only send new WhatsApp messages. It cannot retrieve data.

• The API key must be provided as the authorization key in the request header.

• The rate limit is 1000 requests per second.

• Direct Send for Utility must be enabled for both your account and WhatsApp Business Account.

• Direct Send supports only text and interactive message types.

• Headers in Direct Send messages must be text headers.

• The category and ttl_seconds values are not validated when the request is initially received. Invalid values can fail asynchronously with WhatsApp error code 100.

• preview_url is not supported for Direct Send messages.

• Templates automatically generated by Direct Send are owned by WhatsApp and are view-only. They cannot be edited or deleted.

Direct Send applies the following message limits: