Sandbox (Test API Key)

The document explains how to use our WhatsApp Sandbox Environment.

Introduction

We provide a developer-friendly test environment, for anyone that wants to explore the usage of our WhatsApp API. The WhatsApp API allows for direct-like access to the WhatsApp Business API. In the test environment, you can test sending messages and templates.

Sandbox Base Path: https://waba-sandbox.360dialog.io/

Because of security reasons, in the sandbox environment, each phone number has its own Test API-KEY, and you are able to test sending messages/templates only to your phone number.

Limitations

1. Get a Test API Key

To get a test API-KEY you can:

  • Send a WhatsApp message from your phone to the phone number 4930609859535 with the contentSTART(STARTmust be in all UPPERCASE)

  • Use this QR code:

As a response, you will receive your TestAPIKEY.This API-KEYis associated with your phone WhatsApp number. Now you are able to use the 360dialog WhatsApp API. You can set your own Webhook or send an unlimited number of messages and limited (10) templates.

2. Set your Sandbox Webhook URL

Set Webhook URL

POST https://waba-sandbox.360dialog.io/v1/configs/webhook

Inbound messages sent by you to your WhatsApp Phone Number will be sent to your Webhook. You can use an external service (such as requestbin.com) to test webhook responses, or you can create your own webhook server for tests. In the case you want to test with localhost, you may use an external service (such as ngrok). Use the API-KEY as authorization, with the value D360-API-KEY.

Headers

Name
Type
Description

D360-API-KEY

string

1234567_sandbox

Request Body

Name
Type
Description

url

string

Your webhook URL

{
    "url": "https://your-webhook-url"
}

3. Send a Message to the Sandbox

Now, send another message (any message) from your device to the Sandbox number: 4930609859535.You will receive the Inbound Message Notification on your webhook 😀

4. Respond using the Sandbox API

Send response message

POST https://waba-sandbox.360dialog.io/v1/messages

You can send a response message (or a message template) to your phone WhatsApp number with the above request URL and the body parameters as described below. Use the API-KEY as authorization, with the value D360-API-KEY.

Headers

Name
Type
Description

D360-API-KEY

string

1234567_sandbox

Request Body

Name
Type
Description

recipient_type

string

individual

to

number

Your number

type

string

text (default)

text

object

contains body field

{
    "messages": [
        {
            "id": "message_id"
        }
    ],
    "meta": {
        "api_status": "stable",
        "version": "2.31.5"
    }
}

Example Request Payload

{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "your-number",
    "type": "text",
    "text": {
        "body": "Hello, dear customer!"
    }
}

5. Send a Template Message (optional)

There are 3 templates available to test in the Sandbox. There is no possibility to add or edit a Sandbox templates, you must use the predefined templates. Templates are:

  • disclaimer Using this template will just send a regular text message, which can’t be edited.

  • first_welcome_messsage This is an example of a template with a personalization possibility (you can personalize the receiver's name).

  • interactive_template_sandbox This template contains 2 buttons for which you can pass customer URLs.

Send Template Message

POST https://waba-sandbox.360dialog.io/v1/messages

Headers

Name
Type
Description

D360-API-KEY

string

Sandbox API KEY

Request Body

Name
Type
Description

to

number

Your number

type

string

Message type

namespace

string

Template namespace

language

string

Template language

policy

string

Delivery policy

code

string

Language code

name

string

Template name

{
    "messages": [
        {
            "id": "message_id"
        }
    ],
    "meta": {
        "api_status": "stable",
        "version": "2.35.4"
    }
}

Example Request Payload

first_welcome_messsage

{
  "to": "1234567890",
  "messaging_product": "whatsapp",
  "type": "template",
  "template": {
    "name": "first_welcome_messsage",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Placeholder 1"
          }
        ]
      }
    ]
  }
}

Note that this example covers first_welcome_messsage with personalization. In the case of the disclaimer template, the payload is similar but without the componentsobject (it holds personalization parameters which are not used in disclaimer).

disclaimer

{
  "to": "1234567890",
  "messaging_product": "whatsapp",
  "type": "template",
  "template": {
    "name": "disclaimer",
    "language": {
      "code": "en"
    },
    "components": []
  }
}

interactive_template_sandbox

{
  "to": "1234567890",
  "messaging_product": "whatsapp",
  "type": "template",
  "template": {
    "name": "interactive_template_sandbox",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": 0,
        "parameters": [
          {
            "type": "payload",
            "payload": "aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": 1,
        "parameters": [
          {
            "type": "payload",
            "payload": "aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
          }
        ]
      }
    ]
  }
}

Get new Sandbox API Key

You may recreate / get a new Sandbox API Key at any time by re-sending a WhatsApp message with content START to number 4930609859535. When you create a new API Key for your WhatsApp Number any existing Sandbox Keys associated with your number will be revoked.

Code Examples For Developers

Python

Creating an API key

Send a WhatsApp message START to the number 4930609859535. In the following examples, we assume your phone number is 49YOURNUMBER. Save the D360-API-KEY (in the examples it is described as YOUR_API_KEY).

Setting your Callback URL (optional)

Use an external service (such as requestbin.com) to test webhook responses, or create your own webhook server for tests. In the case you want to test with localhost, you may use an external service (such as ngrok).

#!/usr/bin/env python3
# coding: utf-8
import requests

url = "https://waba-sandbox.360dialog.io/v1/configs/webhook"

payload = '''
    {
        "url": "https://your-webhook-adress"
    }
'''

headers = {
    'D360-Api-Key': "YOUR_API_KEY",
    'Content-Type': "application/json",
}

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

print(response.status_code)
print(response.json())

Now you may send any messages to the number 4930609859535. You will receive all webhooks as described in the WhatsApp API Webhooks Page.

For example, when you send a message with content abcd you will receive a message:

{
    "contacts": [
        {
            "profile": {
                "name": "Your name"
            },
            "wa_id": "49YOURNUMBER"
        }
    ],
    "messages": [
        {
            "from": "49YOURNUMBER",
            "id": "ABGGSHggVwIvAhANFj5aqzEi_lbauSkLYDCO",
            "text": {
                "body": "abcd"
            },
            "timestamp": "1591955533",
            "type": "text"
        }
    ]
}

Test sending messages

#!/usr/bin/env python3
# coding: utf-8
import requests

url = "https://waba-sandbox.360dialog.io/v1/messages"

payload = '''
    {
        "to": "49YOURNUMBER",
        "type": "text",
        "text": {
            "body": "Any message you want..."
        }
    }
'''

headers = {
    'D360-Api-Key': "YOUR_API_KEY",
    'Content-Type': "application/json",
}

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

print(response.status_code)
print(response.json())

In your webhook, you will receive messages about status updates. For example:

{
    "statuses": [
        {
            "id": "gBGGSHggVwIvAgk4hwKJv9PdlG4",
            "recipient_id": "49YOURNUMBER",
            "status": "read",
            "timestamp": "1591955668"
        }
    ]
}

Test sending templates

#!/usr/bin/env python3
# coding: utf-8
import requests

url = "https://waba-sandbox.360dialog.io/v1/messages"

payload = '''
    {
        "to": "49YOURNUMBER",
        "type": "template",
        "template": {
            "namespace": "c8ae5f90_307a_ca4c_b8f6_d1e2a2573574",
            "language": {
                "policy": "deterministic",
                "code": "de"
            },
            "name": "first_welcome_messsage",
            "components": [{
                    "type": "body",
                    "parameters": [{
                            "type": "text",
                            "text": "YOUR NAME"
                        }
                    ]
                }
            ]
        }
    }
'''

headers = {
    'D360-Api-Key': "YOUR_API_KEY",
    'Content-Type': "application/json",
}

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

print(response.status_code)
print(response.json())

Similarly to sending text messages, you will receive webhook calls with status updates.

PHP

Creating an API key

Send a WhatsApp message START to the number 4930609859535. In the following examples, we assume your phone number is 49YOURNUMBER. Save API Key (in examples will be YOUR_API_KEY).

Setting your webhook (optional)

Use external service e.g. requestbin.com to test webhook answers. Or create your own webhook server for tests. In case if you want to test with localhost you may use e.g. external ngrok.com service.

Then set your webhook:

<?php

$url = "https://waba-sandbox.360dialog.io/v1/configs/webhook";

$payload = <<<'PAYLOAD'
    {
        "url": "https://your-webhook-adress"
    }
PAYLOAD;

$headers = [
    "Content-Type: application/json",
    "D360-Api-Key: YOUR_API_KEY",
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "curl error: " . $err;
} else {
    echo $response;
}

Now you may send any messages to the number 4930609859535. You will receive all webhooks as described in the WhatsApp API Webhooks Page.

For example, when you send a message with content abcd you will receive a message:

{
    "contacts": [
        {
            "profile": {
                "name": "Your name"
            },
            "wa_id": "49YOURNUMBER"
        }
    ],
    "messages": [
        {
            "from": "49YOURNUMBER",
            "id": "ABGGSHggVwIvAhANFj5aqzEi_lbauSkLYDCO",
            "text": {
                "body": "abcd"
            },
            "timestamp": "1591955533",
            "type": "text"
        }
    ]
}

Test sending messages

<?php

$url = "https://waba-sandbox.360dialog.io/v1/messages";

$payload = <<<'PAYLOAD'
    {
        "to": "49YOURNUMBER",
        "type": "text",
        "text": {
        	"body": "Any message you want..."
        }
    }
PAYLOAD;

$headers = [
    "Content-Type: application/json",
    "D360-Api-Key: YOUR_API_KEY",
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "curl error: " . $err;
} else {
    echo $response;
}

In your webhook, you will receive messages about status updates. For example:

{
    "statuses": [
        {
            "id": "gBGGSHggVwIvAgk4hwKJv9PdlG4",
            "recipient_id": "49YOURNUMBER",
            "status": "read",
            "timestamp": "1591955668"
        }
    ]
}

Test sending templates

<?php

$url = "https://waba-sandbox.360dialog.io/v1/messages";

$payload = <<<'PAYLOAD'
    {
        "to": "49YOURNUMBER",
        "type": "template",
        "template": {
            "language": {
                "policy": "deterministic",
                "code": "de"
            },
            "name": "first_welcome_messsage",
            "components": [{
                    "type": "body",
                    "parameters": [{
                            "type": "text",
                            "text": "YOUR NAME"
                        }
                    ]
                }
            ]
        }
    }
PAYLOAD;

$headers = [
    "Content-Type: application/json",
    "D360-Api-Key: YOUR_API_KEY",
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "curl error: " . $err;
} else {
    echo $response;
}

Similarly to sending text messages you will receive webhook calls with status updates.

CURL

Creating API Key

Send a WhatsApp message START to the number 4930609859535. In the following examples, we assume your phone number is 49YOURNUMBER. Save API Key (in the examples will be YOUR_API_KEY).

Setting your webhook (optional)

Use external service e.g. requestbin.com to test webhook answers, or create your own webhook server for tests. In the case you want to test with localhost you may use e.g. external ngrok.com service.

Then set your webhook:

curl --request POST \
  --url https://waba-sandbox.360dialog.io/v1/configs/webhook \
  --header 'Content-Type: application/json' \
  --header 'D360-Api-Key: YOUR_API_KEY' \
  --data '{"url": "https://your-webhook-adress"}'

Now you may send any messages to the number 4930609859535. You will receive all webhooks as described in WhatsApp API https://developers.facebook.com/docs/whatsapp/api/webhooks

For example, when you send a message with content abcd you will receive the message:

{
    "contacts": [
        {
            "profile": {
                "name": "Your name"
            },
            "wa_id": "49YOURNUMBER"
        }
    ],
    "messages": [
        {
            "from": "49YOURNUMBER",
            "id": "ABGGSHggVwIvAhANFj5aqzEi_lbauSkLYDCO",
            "text": {
                "body": "abcd"
            },
            "timestamp": "1591955533",
            "type": "text"
        }
    ]
}

Test sending messages

curl --request POST \
  --url https://waba-sandbox.360dialog.io/v1/messages \
  --header 'Content-Type: application/json' \
  --header 'D360-Api-Key: YOUR_API_KEY' \
  --data '{"to":"49YOURNUMBER","type":"text","text":{"body":"Any message you want..."}}'

In your webhook, you will receive messages about status updates. For example:

{
    "statuses": [
        {
            "id": "gBGGSHggVwIvAgk4hwKJv9PdlG4",
            "recipient_id": "49YOURNUMBER",
            "status": "read",
            "timestamp": "1591955668"
        }
    ]
}

Test sending templates

curl --request POST \
  --url https://waba-sandbox.360dialog.io/v1/messages \
  --header 'Content-Type: application/json' \
  --header 'D360-Api-Key: YOUR_API_KEY' \
  --data '{"to": "1234567890", "messaging_product": "whatsapp", "type": "template", "template": { "name": "first_welcome_messsage", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Placeholder 1"}'

Similarly to sending text messages, you will receive webhooks with status updates.

Last updated

Was this helpful?