# WhatsApp Business API

DecisionTelecom WhatsApp API allows you to send and receive WhatsApp business messages to and from any country in the world via API. Each message is identified by a unique random ID, so users can always check the status of a message using given endpoint.

The WhatsApp API uses HTTPS with access key that is used as the API authorization. Request and response payloads are formatted as JSON using UTF-8 encoding.

**API Authorization** - Base64 access key.

Please contact your account manager to get an API key.

## Auth

## Basic Auth

{% tabs %}
{% tab title="Example PHP:" %}

```
$userHashKey = 'User Hash Key provided by your account manager';
	$ch = curl_init('https://web.it-decision.com/v1/api/send-whatsapp');
	curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
	curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
	curl_setopt($ch, CURLOPT_USERPWD, "$userHashKey");
	curl_setopt($ch, CURLOPT_TIMEOUT, 30);
	curl_setopt($ch, CURLOPT_POST, 1);
	curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestParams)); // $requestParams - raquest array with correct data
	curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
	$result = curl_exec($ch);
	curl_close($ch);
```

{% endtab %}
{% endtabs %}

## API Send WhatsApp message

{% tabs %}
{% tab title="POST:" %}

```
https://web.it-decision.com/v1/api/send-whatsapp
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Request POST:" %}

```json
{
    "source_addr": "Custom Company",             
    "destination_addr": 8882222200,              
    "message_type":1,                   
    "text":"Message content",                     
    "file_url":"https://yourdomain.com/images/image.jpg", // file extension is a mandatory attribute
    "callback_url":"https://yourdomain.com/whatsapp-callback",
    "template_name":"image_tmp_en",               
    "template_params":"{
        "to": "recipient_wa_id",
        "type": "template",
        "template": {
        "namespace": "your-namespace",
        "language": {
          "policy": "deterministic",
          "code": "your-language-and-locale-code"
        },
        "name": "your-template-name",
        "components": [
        {
          "type" : "header",
          "parameters": [
          // The following parameters code example includes several different possible header types, 
          // not all are required for a media message template API call.

          {
          "type": "text",
          "text": "replacement_text"
          }

          // OR

          {
          "type": "image",
          "image": {
            "link": "http(s)://the-url",
            # provider is an optional parameter
            "provider": {
            "name" : "provider-name"
            },
          }
          }
        ]
        // end header
        },
        {
          "type" : "body",
          "parameters": [
          {
            "type": "text",
            "text": "replacement_text"
          },
          {
            // Any additional template parameters
          }
          ] 
          // end body
          },
        ]
        }
    }"
  }
```

{% endtab %}
{% endtabs %}

**source\_addr:**

&#x20;           <= 20 chars - from whom the message

**destination\_addr:**

&#x20;           <= 20 chars - to whom the message

**message\_type:**

&#x20;           Type of message to be sent:

&#x20;           1 text message

&#x20;           2 message with media data (jpg, jpeg or png images)

&#x20;           4 message based on registered template

**text:**

&#x20;           <= 4096 chars - text of WhatsApp message

**file\_url:**

&#x20;           Correct URL with image for media message. Correct file extensions:

&#x20;           jpg or jpeg (mime type is image/jpeg)

&#x20;           png (mime type is image/png)

**callback\_url:**

&#x20;           Correct URL  for message status callback    &#x20;

**template\_name:**

&#x20;           Registered template name (only for template message)

**template\_params:**

&#x20;           JSON data of all the necessary parameters to send a template message.&#x20;

{% tabs %}
{% tab title="See details at:" %}

```
 https://developers.facebook.com/docs/whatsapp/api/messages/message-templates/media-message-templates
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Responce JSON (POST):" %}

```json
{
   "message_id":554	
}
```

{% endtab %}
{% endtabs %}

**message\_id:**

Sent message ID

## API Receive WhatsApp message:

{% tabs %}
{% tab title="POST: " %}

```
https://web.it-decision.com/v1/api/receive-whatsapp
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Request POST:" %}

```json
{
   "message_id":554	
}
```

{% endtab %}
{% endtabs %}

**message\_id:**

The ID of the message whose status you want to get

{% tabs %}
{% tab title="Responce JSON:" %}

<pre class="language-json"><code class="lang-json">{
   "message_id":554, 			
<strong>   "status":1, 					
</strong>}
</code></pre>

{% endtab %}
{% endtabs %}

**message\_id:**

The ID of the message whose status you want to get         &#x20;

**status:**

Current WhatsApp message status

## WhatsApp messages statuses

| sent      | 0 |
| --------- | - |
| delivered | 1 |
| rejected  | 2 |
| error     | 3 |
| failed    | 4 |
| deleted   | 5 |
| pending   | 6 |
| seen      | 7 |

## &#x20;Errors

| name    | Too Many Requests   |
| ------- | ------------------- |
| message | Rate limit exceeded |
| code    | 0                   |
| status  | 429                 |

| name    | Invalid Parameter: \[param\_name]             |
| ------- | --------------------------------------------- |
| message | Empty parameter or parameter validation error |
| code    | 1                                             |
| status  | 4                                             |

| name    | Internal server error                                                                         |
| ------- | --------------------------------------------------------------------------------------------- |
| message | The server encountered an unexpected condition which prevented it from fulfilling the request |
| code    | 2                                                                                             |
| status  | 500                                                                                           |

| name    | Topup balance is required |
| ------- | ------------------------- |
| message | User balance is empty     |
| code    | 3                         |
| status  | 402                       |

| name    | Internal server error                                                                         |
| ------- | --------------------------------------------------------------------------------------------- |
| message | The server encountered an unexpected condition which prevented it from fulfilling the request |
| code    | 4, // 5 and 6                                                                                 |
| status  | 500                                                                                           |

| name    | Service Unavailable                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| message | Message failed to send because more than 24 hours have passed since the customer last replied to this number. In this case, you can only send a template message |
| code    | 7                                                                                                                                                                |
| status  | 503                                                                                                                                                              |

| name    | Invalid credintals for file\_url |
| ------- | -------------------------------- |
| message | Invalid MIME type file\_url      |
| code    | 8                                |
| status  | 401                              |

| name    | Invalid credintals for file\_url |
| ------- | -------------------------------- |
| message | Invalid file extension           |
| code    | 9                                |
| status  | 401                              |

## Examples Send WhatsApp message:

{% tabs %}
{% tab title="сURL" %}

```
curl --location 'https://web.it-decision.com/v1/api/send-whatsapp' \
--header 'Authorization: Basic api key' \
--header 'Content-Type: application/json' \
--data ' {"to":"38063xxxxxxx","type":"template","template":{"namespace":"xxxxx_xxxx_xxx_xxx_xxxxx","language":{"policy":"deterministic","code":"en_US"},"name":"media_2_english","components":[{"type":"header","parameters":[{"type":"image","image":{"link":"url image.jpg"}}]}]}}'
```

{% endtab %}

{% tab title=" C#  HttpClient" %}

```
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://web.it-decision.com/v1/api/send-whatsapp");
request.Headers.Add("Authorization", "Basic api key");
var content = new StringContent(" {\"to\":\"38063xxxxxxx\",\"type\":\"template\",\"template\":{\"namespace\":\"xxxxx_xxxx_xxx_xxx_xxxxx\",\"language\":{\"policy\":\"deterministic\",\"code\":\"en_US\"},\"name\":\"media_2_english\",\"components\":[{\"type\":\"header\",\"parameters\":[{\"type\":\"image\",\"image\":{\"link\":\"url image.jpg\"}}]}]}}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

{% endtab %}

{% tab title="GO" %}

```
package main

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

func main() {

  url := "https://web.it-decision.com/v1/api/send-whatsapp"
  method := "POST"

  payload := strings.NewReader(` {"to":"38063xxxxxxx","type":"template","template":{"namespace":"xxxxx_xxxx_xxx_xxx_xxxxx","language":{"policy":"deterministic","code":"en_US"},"name":"media_2_english","components":[{"type":"header","parameters":[{"type":"image","image":{"link":"url image.jpg"}}]}]}}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Basic api key")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
```

{% endtab %}

{% tab title="Java OkHttp" %}

```
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, " {\"to\":\"38063xxxxxxx\",\"type\":\"template\",\"template\":{\"namespace\":\"xxxxx_xxxx_xxx_xxx_xxxxx\",\"language\":{\"policy\":\"deterministic\",\"code\":\"en_US\"},\"name\":\"media_2_english\",\"components\":[{\"type\":\"header\",\"parameters\":[{\"type\":\"image\",\"image\":{\"link\":\"url image.jpg\"}}]}]}}");
Request request = new Request.Builder()
  .url("https://web.it-decision.com/v1/api/send-whatsapp")
  .method("POST", body)
  .addHeader("Authorization", "Basic api key")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();
```

{% endtab %}

{% tab title="C -libcurl" %}

```
CURL *curl;
CURLcode res;
curl = curl_easy_init();
if(curl) {
  curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
  curl_easy_setopt(curl, CURLOPT_URL, "https://web.it-decision.com/v1/api/send-whatsapp";
  curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
  curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");
  struct curl_slist *headers = NULL;
  headers = curl_slist_append(headers, "Authorization: Basic api key");
  headers = curl_slist_append(headers, "Content-Type: application/json");
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  const char *data = " {\"to\":\"38063xxxxxxx\",\"type\":\"template\",\"template\":{\"namespace\":\"xxxxx_xxxx_xxx_xxx_xxxxx\",\"language\":{\"policy\":\"deterministic\",\"code\":\"en_US\"},\"name\":\"media_2_english\",\"components\":[{\"type\":\"header\",\"parameters\":[{\"type\":\"image\",\"image\":{\"link\":\"url image.jpg\"}}]}]}}";
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
  res = curl_easy_perform(curl);
}
curl_easy_cleanup(curl);
```

{% endtab %}

{% tab title="PHP" %}

```
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://web.it-decision.com/v1/api/send-whatsapp',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>' {"to":"38063xxxxxxx","type":"template","template":{"namespace":"xxxxx_xxxx_xxx_xxx_xxxxx","language":{"policy":"deterministic","code":"en_US"},"name":"media_2_english","components":[{"type":"header","parameters":[{"type":"image","image":{"link":"url image.jpg"}}]}]}}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic api key',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}

{% tab title="NodJs" %}

```
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://web.it-decision.com/v1/api/send-whatsapp',
  'headers': {
    'Authorization': 'Basic api key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "to": "38063xxxxxxx",
    "type": "template",
    "template": {
      "namespace": "xxxxx_xxxx_xxx_xxx_xxxxx",
      "language": {
        "policy": "deterministic",
        "code": "en_US"
      },
      "name": "media_2_english",
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "image",
              "image": {
                "link": "url image.jpg"
              }
            }
          ]
        }
      ]
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

{% endtab %}

{% tab title="Python" %}

```
import http.client
import json

conn = http.client.HTTPSConnection("web.it-decision.com")
payload = json.dumps({
  "to": "38063xxxxxxx",
  "type": "template",
  "template": {
    "namespace": "xxxxx_xxxx_xxx_xxx_xxxxx",
    "language": {
      "policy": "deterministic",
      "code": "en_US"
    },
    "name": "media_2_english",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "url image.jpg"
            }
          }
        ]
      }
    ]
  }
})
headers = {
  'Authorization': 'Basic api key',
  'Content-Type': 'application/json'
}
conn.request("POST", "/v1/api/send-whatsapp", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://en-api.decisiontele.com/whatsapp-business-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.