# WhatsApp quickstart

> Connect your WhatsApp number, get a template approved, and send your first WhatsApp message with the API.

This guide takes you from a new project to a delivered WhatsApp message. Connecting the number takes about ten minutes. WhatsApp's template review usually takes a few minutes, and can take up to 24 hours.

## Before you start

- WhatsApp is turned on for your organization: the dashboard sidebar shows **Messaging**. If it doesn't, contact [support@nxiom.com](mailto:support@nxiom.com).
- You are an owner or admin of the organization. Connecting a number and creating API keys need one of these roles.
- You have a phone number that can receive a verification code by SMS or voice call, and that no other WhatsApp account uses. See [Number requirements](/docs/whatsapp/senders#number-requirements).
- You have a phone with WhatsApp installed, to receive the test message.

## Send your first message

### Connect your WhatsApp number

Open **Messaging → WhatsApp**, go to the **Senders** tab, and select **Add sender**. Meta's signup window opens. In it you:

1. Log in with the Facebook account that manages your business.
2. Choose your business portfolio, or create one.
3. Choose your WhatsApp Business Account, or create one, and enter the display name customers will see.
4. Add your phone number and confirm it with the code WhatsApp sends by SMS or voice call.

When the window closes, the number appears in **Senders**. It can send as soon as its status is **Connected**. The full walkthrough, with what to do when a step fails, is in [Connect a WhatsApp number](/docs/whatsapp/senders).

> [!WARNING]
> Keep the signup window open until it finishes, and don't close the dashboard tab. If the window is closed early, nothing is connected and you can start again.

### Create a template

Go to the **Templates** tab and select **Create template**. For this guide, create a utility template:

| Field | Value |
| --- | --- |
| Template name | `order_update` |
| Category | Utility |
| Language | English (US) |
| Body | `Hi {{1}}, your order {{2}} has shipped. You can track it from your account.` |

Give a realistic example for each variable, such as `Amina` and `A-1234`, then select **Submit for review**.

Already have approved templates in WhatsApp Manager? Select **Sync templates** to bring them in instead.

### Wait for approval

WhatsApp reviews every new template. Most reviews take a few minutes; some take up to 24 hours. The template's status changes from **Pending** to **Approved** in the dashboard on its own.

You can only send approved templates. If WhatsApp rejects yours, open it to read the reason, adjust the wording, and submit it again. See [Templates](/docs/whatsapp/templates#review-and-approval).

### Send a test from the dashboard

On the **Overview** tab, use **Send a message**: choose your number and template, enter your own phone number with its country code, fill in the variables, and select **Send message**. The message should arrive on your phone within seconds.

### Create an API key

Open **API keys** and create a key with the **WhatsApp send only** permission. Copy the key when it is shown; it starts with `nc_` and is displayed only once.

```env
NEXIOM_API_KEY=nc_your_api_key
```

### Note your number and template ID

The API needs two values:

- **Your phone number**: the number you connected, in international format, such as `+213555000111`. It is listed in the **Senders** tab.
- **Template ID**: open your template in the **Templates** tab. It starts with `wat_`.

### Send with the API

Send the template on the `whatsapp` channel, from your number to a phone number in international format. Replace `YOUR_PHONE_NUMBER` with your connected number, such as `+213555000111`. The idempotency key makes the request safe to retry: the same key never sends twice. The Node.js and PHP examples use the [Node.js SDK](/docs/examples/nodejs) 0.4.0 and the [PHP SDK](/docs/examples/php) 0.4.0, or later.

```shell title="cURL"
curl -X POST "https://api-connect.nxiom.com/api/v1/messaging/messages" \
  -H "Authorization: Bearer $NEXIOM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-1234-shipped" \
  -d '{
    "channel": "whatsapp",
    "from": "YOUR_PHONE_NUMBER",
    "to": "+213555123456",
    "template": {
      "id": "YOUR_TEMPLATE_ID",
      "variables": {
        "body": { "1": "Amina", "2": "A-1234" }
      }
    }
  }'
```

```typescript title="Node.js"
import { NexiomConnect } from '@nexiom/connect';

const nexiom = new NexiomConnect({ apiKey: process.env.NEXIOM_API_KEY });

const { data, error } = await nexiom.messaging.send(
  {
    channel: 'whatsapp',
    from: 'YOUR_PHONE_NUMBER',
    to: '+213555123456',
    template: {
      id: 'YOUR_TEMPLATE_ID',
      variables: {
        body: { 1: 'Amina', 2: 'A-1234' },
      },
    },
  },
  { idempotencyKey: 'order-A-1234-shipped' },
);

if (error) {
  throw new Error(`${error.code}: ${error.message}`);
}

console.log(data.id, data.status);
```

```php title="PHP"
<?php

use Nexiom\Connect\NexiomConnect;

$nexiom = new NexiomConnect(getenv('NEXIOM_API_KEY'));

$message = $nexiom->messaging->send(
    [
        'channel' => 'whatsapp',
        'from' => 'YOUR_PHONE_NUMBER',
        'to' => '+213555123456',
        'template' => [
            'id' => 'YOUR_TEMPLATE_ID',
            'variables' => [
                'body' => [1 => 'Amina', 2 => 'A-1234'],
            ],
        ],
    ],
    ['idempotencyKey' => 'order-A-1234-shipped'],
);

echo $message['id'], ' ', $message['status'];
```

A `200 OK` response with status `accepted` means WhatsApp accepted the message. Keep the message `id`, which starts with `msg_`.

### Follow the message

[Retrieve the message](/docs/api/messaging/retrieve) with its ID to see it move from `accepted` to `sent`, `delivered`, and `read`, or open **Messaging → Logs**. To be notified instead, [add a webhook](/docs/webhooks) for [whatsapp.message.delivered](/docs/webhooks/whatsapp/delivered) and [whatsapp.message.failed](/docs/webhooks/whatsapp/failed).

## Next steps

- [Key concepts](/docs/whatsapp/key-concepts) Understand display names, template categories, and messaging limits.
- [Sending messages](/docs/whatsapp/sending) Statuses, retries, costs, and error handling.
- [Best practices and FAQ](/docs/whatsapp/best-practices) Opt-in, quality, and a go-live checklist.

---

Source: https://connect.nxiom.com/docs/whatsapp/quickstart