Quickstart

By the end of this guide you’ll have called the GoSendAPI API and gotten a successful send response. We assume you already have a project on GoSendAPI Cloud — if not, create one here (takes 30 seconds).

Sandbox mode: this Quickstart uses a gsk_test_* key. Sends return synthetic responses without actually contacting Meta or delivering to WhatsApp. This lets you test your integration code (HTTP, idempotency, error handling) without spending quota. When you’re ready for real delivery, switch to a gsk_live_* key.

Grab your API key

From the dashboard go to API Keys in the sidebar. A default sandbox key was auto-created when your project was first set up. It looks like:

gsk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

When you need real delivery, click Generate new key and select Production environment — you’ll get a gsk_live_* key.

⚠️

The full key value is shown only once at creation/rotation. Save it in your password manager or environment variables immediately. If lost, rotate to get a new one.

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 (gsk_test_*) you can pass any phone_number_id — the API doesn’t validate it against Meta. Useful for testing your integration before connecting a real WABA.

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 a sandbox key (gsk_test_*), the response is synthetic:

{
  "id": "sandbox-a1b2c3d4e5f6",
  "phone_number_id": "555123456789",
  "direction": "outbound",
  "message_type": "text",
  "wa_message_id": "wamid.SANDBOX.a1b2c3d4e5f6g7h8i9j0k1l2",
  "status": "sent_sandbox",
  "to_phone": "5491140123456",
  "created_at": "2026-05-18T10:00:00.000Z",
  "_sandbox": true,
  "_note": "This response is synthetic. The message was NOT sent to a real WhatsApp recipient. Use a gsk_live_* key to send for real."
}

The _sandbox: true flag and status: "sent_sandbox" confirm no real Meta call was made.

With a live key (gsk_live_*), you get a real send response:

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

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

Watch the status

For live messages, 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_live_..."

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.

Sandbox sends are not persisted (GET /v1/messages won’t list them) and don’t trigger webhooks. They’re purely for integration testing.

What just happened

You authenticated with X-API-Key
We validated the key and identified your project + environment (test vs live)
Sandbox (gsk_test_*): we returned a synthetic response without calling Meta — no real message sent, no persistence, no webhooks
Live (gsk_live_*): we forwarded the message to Meta’s Cloud API with the right access token (encrypted, rotated automatically), persisted the record, and will deliver status updates + inbound replies 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