Sandbox

This documentation describes how to try out the sandbox test environment.

Introduction

We provide a developer friendly test environment, "Sandbox", for anyone that wants to check out the usage of our WhatsApp API. Before you start testing the Sandbox we would like to make you aware of the following restrictions / possibilities:

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 send 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 anytime. If you don't have one yet you can use a free service like RequestBin to set up and endpoint.

  6. Each SandboxAPI key is linked to 1 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 I would advise that you set up a test WABA (Staging WABA) and you can then use it 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 is not supported yet (coming soon).

  3. Templates that can be send are limited to 10. You can choose between 2 predefined templates.

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

  5. We will only forward & trigger 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.

How to use Sandbox for WhatsApp API?

There is only one thing needed:

ust send WhatsApp message from your phone to number 491606232334 with content START. 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 WhatsApp API. You can set your own webhook or send an unlimited number of messages and limited (10) templates.

Please note that media download and upload is not supported (coming soon).

The WhatsApp API allows for direct-like access to WhatsApp for Business API (WhatsApp Business Number). 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 reason, in the sandbox environment, each phone number have own sandbox API key, and you are able to test sending messages/templates only to your phone number.

Sending a Template

There are 2 templates available in the sandbox. There is no possibility to add or edit a sandbox template, you have to use the ones that re already defined. Templates are:

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

  • disclaimer - example of a template without a personalisation. 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. The disclaimer template is a static text that can’t be customised while the first_welcome_messsage has one customisable parameter (receiver’s name). You can read about parameters in WhatsApp Templates Docs.

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

Can I invalidate the current sandbox API key?

Any time you may invalidate/recreate the current API key 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 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:

#!/usr/bin/env python3
# coding: utf-8
import requests
url = "https://waba-sandbox.messagepipe.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 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 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.messagepipe.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 updated. 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.messagepipe.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())

Same as in case of sending text messages you will receive webhook calls with status updates.

PHP

Creating api key

Send a WhatsApp message START to number 491606232334. In 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.messagepipe.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 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 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.messagepipe.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 updated. For example:

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

Test sending templates

<?php
$url = "https://waba-sandbox.messagepipe.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;
}

Same as in case of 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.messagepipe.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 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 message with content abcd you will receive 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.messagepipe.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 updated. For example:

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

Test sending templates

curl --request POST \
--url https://waba-sandbox.messagepipe.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"}]}}'

Same as in case of sending text messages, you will receive webhook calls with status updates.