> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.conversive.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.conversive.ai/_mcp/server.

# WhatsApp Text Message

Send a plain-text WhatsApp message to a recipient.

## Authentication

All requests require an `apiKey` header containing your Conversive API key.

```http
apiKey: <YOUR_API_KEY>
```

> **Note**
>
> Pass the API key as a request header named `apiKey`, not as a Bearer token in the `Authorization` header.

## Request

### Request

POST [https://api.beconversive.com/api/v2/message/send](https://api.beconversive.com/api/v2/message/send)

**`WhatsApp Text Message`**

```curl WhatsApp Text Message
curl -X POST https://api.beconversive.com/api/v2/message/send \
     -H "apiKey: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "userPayload": {
    "type": "api",
    "apiKey": "YOUR_API_KEY"
  },
  "messageDetails": [
    {
      "recipient": [
        {
          "channelType": "whatsapp",
          "phone": "74785939"
        }
      ],
      "sender": {
        "channelType": "whatsapp",
        "phone": "858493494"
      },
      "source": 8001,
      "messageId": "wa-001",
      "message": {
        "type": "text",
        "content": {
          "messageText": "WhatsApp text message"
        }
      }
    }
  ]
}'
```

**`WhatsApp Text Message`**

```python WhatsApp Text Message
import requests

url = "https://api.beconversive.com/api/v2/message/send"

payload = {
    "userPayload": {
        "type": "api",
        "apiKey": "YOUR_API_KEY"
    },
    "messageDetails": [
        {
            "recipient": [
                {
                    "channelType": "whatsapp",
                    "phone": "74785939"
                }
            ],
            "sender": {
                "channelType": "whatsapp",
                "phone": "858493494"
            },
            "source": 8001,
            "messageId": "wa-001",
            "message": {
                "type": "text",
                "content": { "messageText": "WhatsApp text message" }
            }
        }
    ]
}
headers = {
    "apiKey": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`WhatsApp Text Message`**

```javascript WhatsApp Text Message
const url = 'https://api.beconversive.com/api/v2/message/send';
const options = {
  method: 'POST',
  headers: {apiKey: '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"userPayload":{"type":"api","apiKey":"YOUR_API_KEY"},"messageDetails":[{"recipient":[{"channelType":"whatsapp","phone":"74785939"}],"sender":{"channelType":"whatsapp","phone":"858493494"},"source":8001,"messageId":"wa-001","message":{"type":"text","content":{"messageText":"WhatsApp text message"}}}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`WhatsApp Text Message`**

```go WhatsApp Text Message
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beconversive.com/api/v2/message/send"

	payload := strings.NewReader("{\n  \"userPayload\": {\n    \"type\": \"api\",\n    \"apiKey\": \"YOUR_API_KEY\"\n  },\n  \"messageDetails\": [\n    {\n      \"recipient\": [\n        {\n          \"channelType\": \"whatsapp\",\n          \"phone\": \"74785939\"\n        }\n      ],\n      \"sender\": {\n        \"channelType\": \"whatsapp\",\n        \"phone\": \"858493494\"\n      },\n      \"source\": 8001,\n      \"messageId\": \"wa-001\",\n      \"message\": {\n        \"type\": \"text\",\n        \"content\": {\n          \"messageText\": \"WhatsApp text message\"\n        }\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("apiKey", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`WhatsApp Text Message`**

```ruby WhatsApp Text Message
require 'uri'
require 'net/http'

url = URI("https://api.beconversive.com/api/v2/message/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["apiKey"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userPayload\": {\n    \"type\": \"api\",\n    \"apiKey\": \"YOUR_API_KEY\"\n  },\n  \"messageDetails\": [\n    {\n      \"recipient\": [\n        {\n          \"channelType\": \"whatsapp\",\n          \"phone\": \"74785939\"\n        }\n      ],\n      \"sender\": {\n        \"channelType\": \"whatsapp\",\n        \"phone\": \"858493494\"\n      },\n      \"source\": 8001,\n      \"messageId\": \"wa-001\",\n      \"message\": {\n        \"type\": \"text\",\n        \"content\": {\n          \"messageText\": \"WhatsApp text message\"\n        }\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

**`WhatsApp Text Message`**

```java WhatsApp Text Message
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.beconversive.com/api/v2/message/send")
  .header("apiKey", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userPayload\": {\n    \"type\": \"api\",\n    \"apiKey\": \"YOUR_API_KEY\"\n  },\n  \"messageDetails\": [\n    {\n      \"recipient\": [\n        {\n          \"channelType\": \"whatsapp\",\n          \"phone\": \"74785939\"\n        }\n      ],\n      \"sender\": {\n        \"channelType\": \"whatsapp\",\n        \"phone\": \"858493494\"\n      },\n      \"source\": 8001,\n      \"messageId\": \"wa-001\",\n      \"message\": {\n        \"type\": \"text\",\n        \"content\": {\n          \"messageText\": \"WhatsApp text message\"\n        }\n      }\n    }\n  ]\n}")
  .asString();
```

**`WhatsApp Text Message`**

```php WhatsApp Text Message
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beconversive.com/api/v2/message/send', [
  'body' => '{
  "userPayload": {
    "type": "api",
    "apiKey": "YOUR_API_KEY"
  },
  "messageDetails": [
    {
      "recipient": [
        {
          "channelType": "whatsapp",
          "phone": "74785939"
        }
      ],
      "sender": {
        "channelType": "whatsapp",
        "phone": "858493494"
      },
      "source": 8001,
      "messageId": "wa-001",
      "message": {
        "type": "text",
        "content": {
          "messageText": "WhatsApp text message"
        }
      }
    }
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'apiKey' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

**`WhatsApp Text Message`**

```csharp WhatsApp Text Message
using RestSharp;

var client = new RestClient("https://api.beconversive.com/api/v2/message/send");
var request = new RestRequest(Method.POST);
request.AddHeader("apiKey", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"userPayload\": {\n    \"type\": \"api\",\n    \"apiKey\": \"YOUR_API_KEY\"\n  },\n  \"messageDetails\": [\n    {\n      \"recipient\": [\n        {\n          \"channelType\": \"whatsapp\",\n          \"phone\": \"74785939\"\n        }\n      ],\n      \"sender\": {\n        \"channelType\": \"whatsapp\",\n        \"phone\": \"858493494\"\n      },\n      \"source\": 8001,\n      \"messageId\": \"wa-001\",\n      \"message\": {\n        \"type\": \"text\",\n        \"content\": {\n          \"messageText\": \"WhatsApp text message\"\n        }\n      }\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`WhatsApp Text Message`**

```swift WhatsApp Text Message
import Foundation

let headers = [
  "apiKey": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "userPayload": [
    "type": "api",
    "apiKey": "YOUR_API_KEY"
  ],
  "messageDetails": [
    [
      "recipient": [
        [
          "channelType": "whatsapp",
          "phone": "74785939"
        ]
      ],
      "sender": [
        "channelType": "whatsapp",
        "phone": "858493494"
      ],
      "source": 8001,
      "messageId": "wa-001",
      "message": [
        "type": "text",
        "content": ["messageText": "WhatsApp text message"]
      ]
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beconversive.com/api/v2/message/send")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Schema (`request`)

```yaml
openapi: 3.1.0
info:
  title: API
  version: 1.0.0
paths:
  /api/v2/message/send:
    post:
      operationId: sendMessages
      summary: Send Messages
      responses:
        '200':
          description: Messages queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
servers:
  - url: https://api.beconversive.com
    description: US Data Center
  - url: https://eu-api.beconversive.com
    description: EU Data Center
  - url: https://aus-api.beconversive.com
    description: Australia Data Center
  - url: https://qa-api.beconversive.com
    description: QA
  - url: https://staging-api.beconversive.com
    description: Staging
components:
  schemas:
    SendMessageRequestUserPayload:
      type: object
      properties:
        type:
          type: string
        apiKey:
          type: string
      required:
        - type
        - apiKey
      title: SendMessageRequestUserPayload
    ChannelParty:
      type: object
      properties:
        channelType:
          type: string
        phone:
          type: string
      title: ChannelParty
    MessageContentContent:
      type: object
      properties: {}
      title: MessageContentContent
    MessageContent:
      type: object
      properties:
        type:
          type: string
        content:
          $ref: '#/components/schemas/MessageContentContent'
      title: MessageContent
    MessageDetails:
      type: object
      properties:
        recipient:
          type: array
          items:
            $ref: '#/components/schemas/ChannelParty'
        sender:
          $ref: '#/components/schemas/ChannelParty'
        source:
          type: integer
        messageId:
          type: string
        message:
          $ref: '#/components/schemas/MessageContent'
      title: MessageDetails
    SendMessageRequest:
      type: object
      properties:
        userPayload:
          $ref: '#/components/schemas/SendMessageRequestUserPayload'
        messageDetails:
          type: array
          items:
            $ref: '#/components/schemas/MessageDetails'
      required:
        - userPayload
        - messageDetails
      title: SendMessageRequest
    SendMessageResponseResponse:
      type: object
      properties:
        vstatus:
          type: string
        responseText:
          type: string
      title: SendMessageResponseResponse
    SendMessageResponse:
      type: object
      properties:
        response:
          $ref: '#/components/schemas/SendMessageResponseResponse'
      title: SendMessageResponse
    ErrorResponseResponse:
      type: object
      properties:
        vstatus:
          type: string
        responseText:
          type: string
      title: ErrorResponseResponse
    ErrorResponse:
      type: object
      properties:
        response:
          $ref: '#/components/schemas/ErrorResponseResponse'
      title: ErrorResponse

```

## Response

### Schema (`response`)

```yaml
openapi: 3.1.0
info:
  title: API
  version: 1.0.0
paths:
  /api/v2/message/send:
    post:
      operationId: sendMessages
      summary: Send Messages
      responses:
        '200':
          description: Messages queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
servers:
  - url: https://api.beconversive.com
    description: US Data Center
  - url: https://eu-api.beconversive.com
    description: EU Data Center
  - url: https://aus-api.beconversive.com
    description: Australia Data Center
  - url: https://qa-api.beconversive.com
    description: QA
  - url: https://staging-api.beconversive.com
    description: Staging
components:
  schemas:
    SendMessageRequestUserPayload:
      type: object
      properties:
        type:
          type: string
        apiKey:
          type: string
      required:
        - type
        - apiKey
      title: SendMessageRequestUserPayload
    ChannelParty:
      type: object
      properties:
        channelType:
          type: string
        phone:
          type: string
      title: ChannelParty
    MessageContentContent:
      type: object
      properties: {}
      title: MessageContentContent
    MessageContent:
      type: object
      properties:
        type:
          type: string
        content:
          $ref: '#/components/schemas/MessageContentContent'
      title: MessageContent
    MessageDetails:
      type: object
      properties:
        recipient:
          type: array
          items:
            $ref: '#/components/schemas/ChannelParty'
        sender:
          $ref: '#/components/schemas/ChannelParty'
        source:
          type: integer
        messageId:
          type: string
        message:
          $ref: '#/components/schemas/MessageContent'
      title: MessageDetails
    SendMessageRequest:
      type: object
      properties:
        userPayload:
          $ref: '#/components/schemas/SendMessageRequestUserPayload'
        messageDetails:
          type: array
          items:
            $ref: '#/components/schemas/MessageDetails'
      required:
        - userPayload
        - messageDetails
      title: SendMessageRequest
    SendMessageResponseResponse:
      type: object
      properties:
        vstatus:
          type: string
        responseText:
          type: string
      title: SendMessageResponseResponse
    SendMessageResponse:
      type: object
      properties:
        response:
          $ref: '#/components/schemas/SendMessageResponseResponse'
      title: SendMessageResponse
    ErrorResponseResponse:
      type: object
      properties:
        vstatus:
          type: string
        responseText:
          type: string
      title: ErrorResponseResponse
    ErrorResponse:
      type: object
      properties:
        response:
          $ref: '#/components/schemas/ErrorResponseResponse'
      title: ErrorResponse

```

## Errors

| Status Code | Meaning                                     |
| ----------- | ------------------------------------------- |
| 400         | Bad Request — missing or invalid parameters |
| 401         | Unauthorized — invalid or missing API key   |
| 403         | Forbidden — insufficient permissions        |
| 404         | Not Found — endpoint or resource not found  |
| 429         | Too Many Requests — rate limit exceeded     |
| 500         | Internal Server Error — contact support     |

## Common WhatsApp errors

| Code                    | Meaning                                                                                                                                          | Suggested fix                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| 100                     | Request contains unsupported or misspelled parameters                                                                                            | Check field names and length limits                                           |
| 131008                  | A required parameter is missing                                                                                                                  | Check that all required fields are present                                    |
| 131009                  | One or more parameter values are invalid                                                                                                         | Validate values such as phone number format                                   |
| 131021                  | Sender and recipient numbers are the same                                                                                                        | Send to a different recipient                                                 |
| 131026                  | Message undeliverable: recipient may not be on WhatsApp, may not have accepted the latest Terms of Service, or may be on an outdated app version | Ask the recipient to confirm they can message your number and update WhatsApp |
| 130403                  | Your business has blocked this user on WhatsApp                                                                                                  | Do not retry; unblock the user to resume messaging                            |
| 130429                  | Cloud API throughput limit reached                                                                                                               | Retry later or reduce sending rate                                            |
| 131048                  | Sending restricted because too many earlier messages were blocked or flagged as spam                                                             | Check your quality rating in WhatsApp Manager                                 |
| 131056                  | Too many messages to the same recipient in a short period                                                                                        | Wait before retrying; other recipients are unaffected                         |
| 131064                  | Messaging limit reached due to template classification violations (affects template and non-template messages)                                   | Correct template categories; restriction lifts after the enforcement period   |
| 368 / 131031            | WhatsApp Business Account restricted or disabled for a policy violation                                                                          | Review Meta's Policy Enforcement guidelines                                   |
| 130497                  | Account cannot message users in certain countries                                                                                                | Check allowed countries for your business category                            |
| 131042                  | Payment method error                                                                                                                             | Verify WhatsApp Business billing setup                                        |
| 131045                  | Sender number registration error                                                                                                                 | Register the sender phone number                                              |
| 133010                  | Sender number not registered on the WhatsApp Business Platform                                                                                   | Register the sender phone number                                              |
| 131057                  | Business account is in maintenance mode                                                                                                          | Retry after a few minutes                                                     |
| 1 / 2 / 131000 / 131016 | Invalid request, server error, downtime, or temporary service outage                                                                             | Check the WhatsApp Business Platform Status page, then retry                  |

## WhatsApp Text Message and WhatsApp Media Message: Session message errors

| Code   | Meaning                                             | Suggested fix                   |
| ------ | --------------------------------------------------- | ------------------------------- |
| 131047 | More than 24 hours since the recipient last replied | Send a template message instead |
| 131051 | Message type not supported                          | Use a supported message type    |

## WhatsApp Media Message and WhatsApp Media Template: Media errors

| Code   | Meaning                                                   | Suggested fix                                                                |
| ------ | --------------------------------------------------------- | ---------------------------------------------------------------------------- |
| 131053 | Media could not be uploaded (e.g. unsupported media type) | Confirm the file's MIME type is supported and the URL is publicly accessible |

## WhatsApp Template Message and WhatsApp Media Template: Template errors

| Code   | Meaning                                                           | Suggested fix                                                              |
| ------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 132000 | Number of variable values doesn't match the template's variables  | Send one value for each template variable                                  |
| 132001 | Template not found in the given language, or not approved         | Check template `name`, `language.code`, and approval status                |
| 132005 | Translated text is too long                                       | Check the template translation in WhatsApp Manager                         |
| 132007 | Template content violates WhatsApp policy                         | Review and revise the template content                                     |
| 132012 | Variable values don't match the format defined in the template    | Match each parameter type to the template (e.g. image for an image header) |
| 132015 | Template paused due to low quality                                | Edit the template and resend once re-approved                              |
| 132016 | Template permanently disabled after repeated pauses               | Create a new template with different content                               |
| 131049 | Not delivered due to per-user marketing message limits            | Wait at least 24 hours before resending                                    |
| 131050 | Recipient has opted out of your marketing messages                | Do not retry                                                               |
| 131063 | Marketing templates are disabled for this Cloud API configuration | Use the Marketing Messages API or re-enable marketing templates            |