Your First WhatsApp Message Through a REST API, Step by Step

Here is the whole job in one sentence: you ask a server, over the internet, to send a WhatsApp message, and it does. If that sounds like less than you expected, good. The scary parts are mostly vocabulary.

This walkthrough assumes you have a gateway or provider account and at least one connected number. Field names differ between providers, so treat our examples as the general shape and follow your provider's own documentation for exact names.

Words you will see

• Endpoint: the web address you send your request to.
• Request: the message you send to that address, containing instructions.
• Header: extra information attached to the request, such as your API key.
• Body: the main content, usually written in JSON, with the number and the text.
• Response: what comes back, telling you if it worked.

Step 1: get a key and a connected number

Create an API key in your dashboard. In WA Getway this is where you generate keys for the REST API. Treat the key like a password. Paste it into a notes file for now, not into anything that will be shared or committed to a code repository. We cover this properly in keeping API keys safe.

You also need a connected sender, which is either a number linked by QR or one registered with the official Cloud API.

Step 2: send it to yourself

Use your own mobile number as the recipient, written in international format: country code first, no plus sign or spaces unless your provider asks for them. For India that begins with 91. Sending to yourself means a mistake costs you nothing.

Step 3: make the request

From a terminal, a tool called curl is the easiest way. The request has a pattern like this, and yours will differ in the field names:

`POST /send` with a header that carries your key, and a body such as the recipient number and the text 'Hello from my first API call'. In curl you add the header with the -H flag and the body with the -d flag.

Prefer not to use a terminal? Free tools like Postman or Insomnia give you boxes to fill in for the address, header and body. They do the same thing with buttons.

Step 4: read what comes back

1. 1A success status, often a number starting with 2, means the request was accepted.
2. 2Accepted is not the same as delivered. The message may still be waiting in a queue.
3. 3An authentication error, usually a 401 or 403, means the key is wrong or missing.
4. 4A validation error, often a 400, means something in your body is off, like a badly formatted number.
5. 5Check your phone. The message should appear within moments.

That gap between 'accepted' and 'delivered' trips up almost everyone. It is explained in sent, delivered and read.

Step 5: try something other than text

Once plain text works, try an image or a document. Media messages usually take a link to the file or an upload, plus an optional caption. Start with a small image. Large files take longer and are more likely to time out.

What not to do on day one

• Don't loop through a list of real customers to 'see if it works'.
• Don't put the key in a public file, screenshot or chat message.
• Don't ignore the response. Read it every time, even when it looks fine.
• Don't send the same test message many times quickly. Gateways pace messages for a reason, as described in queues and pacing.

A word on phone number formats

A large share of first-day errors come down to numbers. Some providers want the country code with no plus sign, some want the plus, and some want a special suffix. A number saved with a leading zero will fail where the same number with 91 in front would work. Pick one clean format in your own system, such as digits only with the country code, and convert at the last step to whatever your provider expects.

Keep a note of the exact request that worked. When something breaks three months from now, a known good example is the fastest way to find the difference.

Where to go next

Once one message works, the rest is repetition and good habits. Add a test routine, covered in testing a WhatsApp integration without spamming customers, then connect the call to your website or app. If you get stuck on a particular error, send us the response you got and we'll help you read it.