# Send And Receive Messages

### Prerequisites

Ensure the following are available:

* An approved WhatsApp Business Account (WABA)
* A registered phone number
* An API Key
* A HTTPS webhook endpoint

Basic knowledge of REST APIs and webhooks is recommended.

{% stepper %}
{% step %}

### Understand Customer Service Windows

WhatsApp messaging follows a conversation-based model using **customer service windows**.

Free-form messages can only be sent when a customer service window is open.

A customer service window opens when:

* A WhatsApp user sends a message to the business phone number, or
* A template message is sent and delivered to the user

If no customer service window exists, text messages sent using the API will not be delivered.

To start messaging for the first time, one of the following must occur:

* The user messages the business number first, or
* A template message is sent to initiate the conversation
  {% endstep %}

{% step %}

### Prepare The API Request

All Messaging API requests use the base URL:

```bash
https://waba-v2.360dialog.io
```

Messages are sent using the endpoint:

```bash
POST /messages
```

Full request URL:

```bash
POST https://waba-v2.360dialog.io/messages
```

{% endstep %}

{% step %}

### Authorise The Request

Add the API Key header to every request:

```
D360-API-KEY: {{api-key}}
```

Requests sent without an API key will be rejected. 

{% endstep %}

{% step %}

### Send a message

Option A: Send A Text Message (Customer Service Window Open)

When a customer service window is open, send a free-form text message using the API.

```bash
curl \
  -X POST https://waba-v2.360dialog.io/messages \
  -H "D360-API-KEY: {{api-key}}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "PHONE_NUMBER",
    "type": "text",
    "text": {
      "body": "Hello from WhatsApp API"
    }
  }'
```

A successful response returns a message ID confirming the request was accepted.<br>

Option B: Send A Template Message (No Customer Service Window Open)

If no customer service window is open, a template message must be sent to initiate the conversation.

Template messages must be approved before use.

Example template message request:

```bash
curl \
  -X POST https://waba-v2.360dialog.io/messages \
  -H "D360-API-KEY: {{api-key}}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "PHONE_NUMBER",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": {
        "code": "en_US"
      }
    }
  }'
```

{% endstep %}

{% step %}

### Configure A Webhook

Webhooks deliver real-time events when messages are sent or received.

Configure a callback URL that:

* Uses HTTPS
* Has a valid SSL certificate
* Returns HTTP status `200 OK` for all incoming requests
* Responds quickly (max latency 80ms)

Webhook events include:

* Incoming user messages
* Message status updates (`sent`, `delivered`, `read`)

If a webhook delivery fails or a non-200 status code is returned, the WhatsApp Business Platform retries delivery using exponential backoff for several days (up to 7 days) or until delivery succeeds.

There are several options to [**set the webhook URL**](https://docs.360dialog.com/docs/messaging-api/api-reference/webhooks) using our API.&#x20;

{% endstep %}

{% step %}

### Test Incoming Messages

1. Send a WhatsApp message from a mobile device to the business number.
2. Observe the webhook endpoint.
3. Confirm an incoming message payload is received.

Receiving webhook events confirms messaging is fully operational.
{% endstep %}
{% endstepper %}