> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/partner/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/partner/onboarding/partner-api-sandbox.md).

# Partner API Sandbox

This page describes how partner API sandbox can be used to send testing messages to a phone number on WhatsApp.

## Overview

The Partner Sandbox allows partners to quickly connect a personal WhatsApp number and test the 360Dialog messaging APIs - including text messages, interactive messages, template messages, and webhook events - without needing a full WABA setup.

## Accessing the Sandbox

After logging into the 360Dialog Partner Hub, select **Sandbox** from the navigation panel on the right. 

{% hint style="info" %}
Partners can access the Partner Sandbox without requiring a paid plan. The Partner Sandbox is included with all Partner Plans.
{% endhint %}

<figure><img src="https://2248475362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuyAl2S0lSHJaNDXJHo7A%2Fuploads%2FqxGwKkx7ifOeelXOHfqR%2Fimage.png?alt=media&amp;token=659196f0-420e-40dc-87b2-3e79119870b8" alt=""><figcaption></figcaption></figure>

## Getting Started

{% hint style="info" %}
Sandbox Usage Limit

Each sandbox test account can send a maximum of **200 messages**. Once the limit is reached, further requests fail with **HTTP 429**. Every request that reaches the messaging API counts towards the limit, even if the message itself is rejected.
{% endhint %}

{% stepper %}
{% step %}

### Register A Test Number

<figure><img src="https://2248475362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuyAl2S0lSHJaNDXJHo7A%2Fuploads%2Fh42YAsGseODs9iauWbQr%2Fimage.png?alt=media&amp;token=bb7d0f9c-7327-4778-9f1c-adabbc29bc9c" alt=""><figcaption></figcaption></figure>

Click "Connect" and enter a personal WhatsApp phone number you currently have access to.

Before sending test messages to this phone number, a message needs to be sent on WhatsApp from the phone number to the 360Dialog sandbox number. For this, a QR code will appear along with a **Send Connection Code** button. Next:

* **Scan the QR code** to open WhatsApp directly on a mobile device.
* **Or click the button** to open WhatsApp Web or WhatsApp Desktop with a pre-filled connection message.

Both options send a pre-filled message to the 360Dialog sandbox number.

<figure><img src="https://2248475362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuyAl2S0lSHJaNDXJHo7A%2Fuploads%2FIOxtB4LpdqUGgRQrMraT%2Fimage.png?alt=media&amp;token=b336f8c6-8739-42e1-979c-0e9e8d75bd43" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Once the 360Dialog sandbox number receives a message sent from WhatsApp, all remaining steps will unlock automatically.
{% endhint %}

{% hint style="info" %}
**Connection Message Behavior**

Depending on the WhatsApp configuration of the sending device, WhatsApp may deliver the connection message without the phone number. The connection code alone is sufficient in that case, so registration completes and the status badge still changes to **Connected**. The test number shown in the Hub is always the number entered in the form.
{% endhint %}

Once the connection is established, the status badge changes to **Connected.**
{% endstep %}

{% step %}

### Send a Basic Text Message

Send a simple text message from the sandbox number to the connected number.

This section includes a message preview showing how the message will appear in WhatsApp, a configurable text field (defaulting to "Hello World! 👋"), a **Send Message** button, and the equivalent cURL command for the API call.

The cURL example uses the sandbox endpoint:

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

The generated API key is included in the `D360-API-KEY` header.

{% hint style="info" %}
**Business-Scoped User ID (BSUID) Compatibility**

The messaging API also accepts a `recipient` field instead of `to` for test accounts that are identified by a **business-scoped user ID (BSUID)** rather than a phone number.
{% endhint %}
{% endstep %}

{% step %}

### Send an Interactive Message

Test sending a pre-approved message with interactive buttons. The message preview shows a greeting message with two button options - for example, "Speak with an agent" and "Get Pricing Information."

Both a **Send Message** button and the corresponding cURL command are provided. This step uses the `interactive_template_sandbox` template.
{% endstep %}

{% step %}

### Send a Marketing Message

Send a template message via the MM API endpoint, designed for high-throughput marketing campaigns. In the sandbox, all messages, including marketing templates, go through the same endpoint `https://waba-sandbox.360dialog.io/v1/messages` . In production, marketing campaigns use the dedicated high-throughput [MM API endpoint](https://docs.360dialog.com/docs/messaging-api/api-reference/marketing-messages#post-marketing-marketing_messages).

The message preview shows a marketing template with a header image, body text, and a "Shop Now" CTA button. The template used is `marketing_message`. The cURL command targets the same sandbox endpoint.<br>

<figure><img src="https://2248475362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuyAl2S0lSHJaNDXJHo7A%2Fuploads%2F8xp9RsVB7C0cQk26Q759%2Fimage.png?alt=media&amp;token=bac6b4e4-b2a6-4e4d-9a71-2764e000d45e" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## Webhook Events

The right-hand panel displays webhook events in real time. It includes:

* A **Webhook URL** field (initially set to `N/A`) with an **Edit** button to configure the own webhook endpoint. The URL must use **HTTPS** (a plain `http://` URL is rejected). Optional custom headers can be stored alongside the URL and are then sent with every webhook delivery.
* A **refresh** button to manually reload events.

New events are highlighted with a blue outline. Clicking any event row displays its full JSON payload in the **Event Payload** section.

### Webhooks and Business-Scoped User IDs (BSUID)

If WhatsApp does not share the phone number of the connected device, events identify the contact by its **business-scoped user ID (BSUID)** instead.

The Business-Scoped User ID is an opaque, per-business identifier that WhatsApp assigns to a user for one specific business when their phone number is not shared.

In the event payload, the BSUID appears as:

* `from_user_id` on inbound messages
* `recipient_user_id` on status events
* `user_id` inside contacts

These events are still listed in the panel and delivered to your configured webhook URL.

## FAQ

<details>

<summary>Why is my registration status stuck in "Pending"?</summary>

If you sent the connection message but the status did not update, verify if WhatsApp delivered the connection message. Starting with sandbox release version 0.3.0, if WhatsApp withholds the phone number, the connection code alone is sufficient to complete registration and update the badge to **Connected**.

</details>

<details>

<summary>What is a Business-Scoped User ID (BSUID)?</summary>

It is an identifier that WhatsApp assigns to a user for a specific business. WhatsApp sends it instead of the phone number when the user's phone number is not shared with the business.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.360dialog.com/partner/onboarding/partner-api-sandbox.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.