Quickstart

By the end of this guide you’ll have sent a real WhatsApp message from your backend. We assume you already have a project on GoSendAPI Cloud — if not, create one here (takes 30 seconds).

Grab your API key

From the dashboard go to API Keys in the sidebar and copy your sandbox key. It looks like:

gsk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The gsk_test_ prefix means it’s a sandbox key — messages go through Meta’s test number and don’t cost anything. When you’re ready for production, rotate to a gsk_live_ key.

⚠️

The key is shown only once when you create it. Save it in your password manager or environment variables immediately.

Find your phone_number_id

Each WhatsApp number connected to your project has a unique phone_number_id from Meta. You can find it in Phone numbers in the dashboard, or via the API:

curl https://cloud.gosendapi.com/v1/wabas \
  -H "X-API-Key: gsk_test_..."

The response lists every WABA in your project — drill into one to see its phone numbers:

curl https://cloud.gosendapi.com/v1/wabas/{waba_id}/phone-numbers \
  -H "X-API-Key: gsk_test_..."

Look for the phone_number_id field (a long numeric string from Meta, not the human-readable phone).

In sandbox mode you get a pre-provisioned test number — its phone_number_id is visible in the dashboard under Phone numbers → Sandbox.

Send the message

With your API key and phone_number_id ready, send the message:

curl https://cloud.gosendapi.com/v1/messages \
  -H "X-API-Key: gsk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "555123456789",
    "to": "5491140123456",
    "type": "text",
    "text": { "body": "Hello from GoSendAPI 👋" }
  }'

const res = await fetch('https://cloud.gosendapi.com/v1/messages', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.GOSENDAPI_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone_number_id: '555123456789',
    to: '5491140123456',
    type: 'text',
    text: { body: 'Hello from GoSendAPI 👋' },
  }),
});
 
const data = await res.json();
console.log(data.id, data.wa_message_id);

$ch = curl_init('https://cloud.gosendapi.com/v1/messages');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('GOSENDAPI_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'phone_number_id' => '555123456789',
  'to' => '5491140123456',
  'type' => 'text',
  'text' => ['body' => 'Hello from GoSendAPI 👋'],
]));
 
$response = json_decode(curl_exec($ch), true);
echo $response['id'];

import os
import requests
 
res = requests.post(
    'https://cloud.gosendapi.com/v1/messages',
    headers={
        'X-API-Key': os.environ['GOSENDAPI_KEY'],
        'Content-Type': 'application/json',
    },
    json={
        'phone_number_id': '555123456789',
        'to': '5491140123456',
        'type': 'text',
        'text': {'body': 'Hello from GoSendAPI 👋'},
    },
)
print(res.json()['id'])

You should get back a 200 OK with the message record:

{
  "id": "1234567890",
  "phone_number_id": "555123456789",
  "direction": "outbound",
  "message_type": "text",
  "wa_message_id": "wamid.HBgLN...",
  "status": "sent",
  "payload": "...",
  "created_at": "2026-05-17T10:00:00.000Z"
}

The wa_message_id is Meta’s tracking ID — you’ll see it again in webhook delivery events.

Watch the status

WhatsApp delivers status updates asynchronously (sent → delivered → read). Either poll the message:

curl https://cloud.gosendapi.com/v1/messages/{message_id} \
  -H "X-API-Key: gsk_test_..."

Or subscribe to webhooks (recommended). Configure one in the dashboard → Webhooks and we’ll POST to your endpoint every time a status changes. See the Webhooks guide.

What just happened

You authenticated with X-API-Key
We validated the key, identified your project and located the phone_number_id you specified
We forwarded the message to Meta’s Cloud API with the right access token (kept encrypted, rotated automatically)
Meta returned a wa_message_id — we persisted it linked to your project
Meta will continue sending status updates and any inbound reply via webhook

Next steps

For messages outside the 24h window, you need an approved template. Learn how to create and send one.

Templates

Wire up event delivery so you don’t poll. Includes HMAC verification examples.

Webhooks

Want your end customers to connect their own WhatsApp number? Generate a Setup Link.

Setup Links

Every error code you might hit, with the fix.

Errors

Introduction Authentication