WhatsApp quickstart

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.
• 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.
• You have a phone with WhatsApp installed, to receive the test message.

Send your first message#

1. 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.

2. 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.

3. 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.

4. 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.

5. 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

6. 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_.

7. 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 0.4.0 and the PHP SDK 0.4.0, or later.

   cURLNode.jsPHP

   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" }
         }
       }
     }'

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

8. Follow the message

   Retrieve the message 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 for whatsapp.message.delivered and whatsapp.message.failed.

Next steps#