WhatsApp API Sandbox

This part of the documentation describes how to try out the 360dialog sandbox test environment for WhatsApp messaging.

Introduction

We provide a developer-friendly test environment, "Sandbox", for anyone that wants to check out the usage of our WhatsApp API. The WhatsApp API allows for direct-like access to WhatsApp for Business API. In the sandbox, you can test sending messages/templates as described in WhatsApp messages docs and receive a Webhook as described in WhatsApp Webhook docs.

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

Because of security reasons, in the sandbox environment, each phone number have their own sandbox API Key, and you are able to test sending messages/templates only to your phone number.

Setup the Sandbox for the WhatsApp Business API

To set up the sandbox you can either: 1. send a WhatsApp message from your phone to the phone number 491606232334 with content START

or 2. you can use this link: https://wa.me/491606232334?text=START

As an answer, you receive your sandbox API KEY.This API Key is connected with your phone (WhatsApp) number. Now you are able to use the WhatsApp API. You can set your own Webhook or send an unlimited number of messages and limited (10) templates.

What you can do with the Sandbox:

  1. You can use the Sandbox to send text messages and text templates to your own phone number.

  2. An unlimited amount of messages can be sent with the sandbox.

  3. Your phone number acts like a user and can send and receive messages.

  4. The number can be a landline number, as long it is able to use Whatsapp.

  5. You can switch the endpoint at any time. If you don't have one yet you can use a free service like RequestBin to set up an endpoint.

  6. Each SandboxAPI Key is linked to one phone number and you can only send test messages to that phone number. If you wish to test messages with more than 1 number then it is advised to set up a test WhatsApp Business Account (Staging WABA) to use instead of the Sandbox.

What you can't do with the Sandbox:

  1. The Sandbox is a test environment only. You will not be able to use it to send messages to your clients. You can only send messages to your own phone number.

  2. Media download and upload are not supported yet (coming soon).

  3. Templates messages can be sent a maximum of 10 times. You can choose between 2 predefined templates.

  4. Messages and Templates can be sent only to your own phone number.

  5. We will only forward and trigger an API when your given number is involved.

  6. We do not yet provide response information when you use the WhatsApp API.

  7. You only have access to the WhatsApp API.

  8. Our Sandbox is available to test via the API, but any automated tests would have to be configured from your end.

Sending a Template Message

There are 2 templates available in the sandbox. There is no possibility to add or edit a sandbox template, you must use the predefined templates. Templates are:

  • first_welcome_message_ example of a template with a personalisation possibility: - You can personalise the receiver's name.

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

You always have to use the predefined namespace which is c8ae5f90_307a_ca4c_b8f6_d1e2a2573574.

Templates example: already described here: Test Sending Templates. Note that this example covers “first_welcome_messsage” with personalisation. In the case of the “disclaimer” template, the payload is almost the same, just without the “localizable_params” section (it holds personalisation parameters which are not used in disclaimer).

Can I invalidate the current sandbox API Key?

You may invalidate/recreate the current API Key at any time, by sending again WhatsApp message with content START to number 491606232334.

Step By Step Tutorial:

Python

Creating an API key

Send a Whatsapp message START to the number 491606232334. In the following examples, we assume your phone number is 49YOURNUMBER. Save the API Key (in the examples it is described as YOUR_API_KEY).

Setting your webhook (optional)

Use external service f.e. 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 f.e. external ngrok.com service.

Then set your webhook:

#!/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 491606232334. 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",
"ttl": "P1D",
"type": "hsm",
"hsm": {
"namespace": "c8ae5f90_307a_ca4c_b8f6_d1e2a2573574",
"element_name": "first_welcome_messsage",
"language": {
"policy": "deterministic",
"code": "de"
},
"localizable_params": [
{
"default": "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 491606232334. 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 f.e. 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 f.e. 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 491606232334. 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",
"ttl": "P1D",
"type": "hsm",
"hsm": {
"namespace": "c8ae5f90_307a_ca4c_b8f6_d1e2a2573574",
"element_name": "first_welcome_messsage",
"language": {
"policy": "deterministic",
"code": "de"
},
"localizable_params": [
{
"default": "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 491606232334. 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 f.e. 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 f.e. 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 491606232334. 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":"49YOURNUMBER","ttl":"P1D","type":"hsm","hsm":{"namespace":"c8ae5f90_307a_ca4c_b8f6_d1e2a2573574","element_name":"first_welcome_messsage","language":{"policy":"deterministic","code":"de"},"localizable_params":[{"default":"your name"}]}}'

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