ShipMsgDocs
Contents

Get started

Quickstart: your first sandbox message

In about ten minutes you will create an API key, send a WhatsApp message from your sandbox number, and watch it move from queued to delivered to read. Nothing here reaches a real phone and nothing is billed.

1. Create an account

Sign up and confirm your e-mail. Every new account gets a sandbox automatically: a test WhatsApp sender that is already connected, so you do not need a Meta Business account to start.

2. Create a sandbox API key

  1. In the console, open Developer → API keys and make sure the environment switch says Sandbox.
  2. Create a key. Copy the secret: it starts with sk_test_ and is shown only once.
  3. Copy your account SID (AC…; every console address carries it as accountSid=AC…) and your sandbox sender SID (WA…, listed under Senders).
shell
export SHIPMESSAGES_API_KEY="sk_test_..."
export SHIPMESSAGES_ACCOUNT_SID="AC..."
export SHIPMESSAGES_SANDBOX_SENDER_SID="WA..."

3. Choose HTTPS or an SDK

Use the curl examples below to call the API directly. The pre-release SDKs are packaged, but public registry publication is pending. The SDK tabs document their interfaces for the upcoming release.

4. Send a message

+15550000001 is a sandbox test number: every message to it is sent, delivered and read within a few seconds. See all test numbers.

curl -X POST "https://api.shipmsg.com/v1/accounts/$SHIPMESSAGES_ACCOUNT_SID/messages" \
  -H "Authorization: Bearer $SHIPMESSAGES_API_KEY" \
  -H "ShipMessages-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "'"$SHIPMESSAGES_SANDBOX_SENDER_SID"'",
  "to": "+15550000001",
  "type": "text",
  "text": {
    "body": "Hello from the ShipMsg sandbox"
  }
}'

The answer is 202 Accepted with the new message:

response
{
  "object": "message",
  "sid": "SM4AZTTK56XRT49RC2FGMFK4XYJG",
  "status": "queued",
  "direction": "outbound",
  "from": "WA…",
  "to": { "identifierType": "phone_e164", "value": "+15550000001", "contactSid": "CT…" },
  "type": "text",
  "livemode": false,
  …
}

5. Watch it get delivered

Read the message back after a few seconds:

curl
curl "https://api.shipmsg.com/v1/accounts/$SHIPMESSAGES_ACCOUNT_SID/messages/SM..." \
  -H "Authorization: Bearer $SHIPMESSAGES_API_KEY"

Its status moves queued → sent → delivered → read. In a real integration you do not poll: you receive each change as a message.sent, message.delivered and message.read event. The console shows the same history under Messages.

Next steps

  • Set up a webhook to receive statuses and replies.
  • Send to +15550000012: it replies “hello” five seconds after delivery, so you can test inbound messages.
  • Outside the sandbox, the first message to a customer must be an approved template.
  • When you are ready, connect your own number in the console and switch to an sk_live_ key.