The site is currently in beta.
WhatsApp API

WhatsApp API reference: every endpoint, field and error code

Smart One Group support teamLast updated: 9 min read

Short answer

The Smart One Group WhatsApp API lives at https://sog.sog.eg/api/whatsapp, and every request carries the appkey and authkey from the “Link API” tab. Use /send for text, images, files and templates and /messages/{id} to check a message, alongside endpoints for templates, scheduling, campaigns, chatbot rules and webhooks. Every response is JSON; errors carry a message and a code that names the cause.

On this page

What are the basics of the API?

  • Base URL: https://sog.sog.eg/api/whatsapp.
  • Authentication: send appkey and authkey with every request; in the body for POST, in the query string for GET.
  • Format: requests in JSON or form encoding, responses always JSON. Add the Accept: application/json header so field validation errors come back as JSON.
  • Limits: up to 60 requests a minute from the same IP address, on top of your package minimum seconds between messages.
MethodEndpointUse
POST/create-messageSend text only (simplest)
POST/sendSend text, an image, a file or a template
GET/messages/{id}Status of a message you sent
GET / POST/templatesList templates or create one
POST/contactsSave a contact and their consent
POST/scheduleSchedule a message for later
POST/campaignsCreate a campaign (draft)
POST/campaigns/{id}/start|pause|cancelStart, pause or cancel a campaign
POST/chatbot/rulesAuto-reply rule
GET/inboxLatest 100 incoming messages
POST/webhooksRegister a webhook URL
POST/sandboxTest keys that never really send

How do I send text, an image, a file or a template?

Use POST /send. Only to is always required; the rest depends on the message:

FieldDescription
toRecipient in international format, such as 201012345678 (local Egyptian numbers are accepted).
typetext (default), image, video, audio, voice or document.
messageMessage text, or the file caption. Up to 4,096 characters.
captionFile caption when you do not send message. Up to 1,000 characters.
media_urlA direct public link to the file (no redirects), up to 16 MB.
fileUpload the file directly as multipart, up to 32 MB.
template_idOne of your template ids; the template text becomes the message.
variablesTemplate values, such as {"name": "Ahmed"} to fill {name}. Names use lowercase letters, digits and _.
Idempotency-Key headerA unique key per message (up to 80 characters). Repeat a request with the same key after it succeeded and you get the same response without a second message.
curl -X POST https://sog.sog.eg/api/whatsapp/send \
  -H "Accept: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
  -d to=201012345678 \
  -d message="Your order #1042 is confirmed ✅"

Images and files need the Send files feature in your package; templates need the Templates feature.

How do I check a message I sent?

Use GET /messages/{id}, where id is data.id from the send response. Possible status values:

StatusMeaning
queuedThe message is on its way out of your number.
sentIt left your number and WhatsApp accepted it.
failedIt was not sent; the code field says why.
sandboxA test message sent with sandbox keys; nothing was delivered.
curl -G https://sog.sog.eg/api/whatsapp/messages/4182 \
  -H "Accept: application/json" \
  --data-urlencode appkey=YOUR_API_KEY \
  --data-urlencode authkey=YOUR_SECRET_KEY

How do I use templates?

A template is saved text with variables in braces, such as {name}. Create it once with POST /templates, then send it with template_id and variables on /send. How many you can keep depends on your package Template limit.

curl -X POST https://sog.sog.eg/api/whatsapp/templates \
  -H "Accept: application/json" \
  -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
  -d name="Order confirmed" \
  -d body="Hi {name}, your order #{order_id} is confirmed."

# → 201 {"data":{"id":7,"name":"Order confirmed"}}

When a recipient replies STOP or إيقاف, their number is marked as opted out, and any later send to it returns 403 with the code opted_out. If they agree again, register them with POST /contacts and opted_in=1.

curl -X POST https://sog.sog.eg/api/whatsapp/contacts \
  -H "Accept: application/json" \
  -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
  -d phone=201012345678 -d name="Ahmed" -d opted_in=1

# → 200 {"data":{"phone":"201012345678","opted_in":true}}

How do I schedule a message for later?

Send POST /schedule with to, message and send_at. Write the time in ISO 8601 with its offset, such as +02:00; a time without an offset is read as UTC. Due messages go out every minute from your first active app.

curl -X POST https://sog.sog.eg/api/whatsapp/schedule \
  -H "Accept: application/json" \
  -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
  -d to=201012345678 \
  -d message="Reminder: your appointment is tomorrow at 10:00" \
  --data-urlencode send_at=2026-11-20T09:00:00+02:00

# → 201 {"data":{"id":31,"send_at":"2026-11-20T07:00:00+00:00"}}

How do I send a campaign to many customers?

Create it with POST /campaigns (up to 500 numbers per request); it is saved as a draft, then start it with /campaigns/{id}/start. Send consent: true to confirm these numbers agreed to hear from you; without it, numbers not on file as opted in are skipped and listed in skipped.

A campaign goes out gradually, about one message a minute per campaign, and pauses during the quiet hours between quiet_start and quiet_end (UTC). You can also follow, start and pause campaigns on the Campaigns tab in the portal.

POST https://sog.sog.eg/api/whatsapp/campaigns
Accept: application/json
Content-Type: application/json

{
  "appkey": "YOUR_API_KEY",
  "authkey": "YOUR_SECRET_KEY",
  "name": "Black Friday",
  "body": "Black Friday: 30% off all plans until Sunday. Reply STOP to opt out.",
  "phones": ["201012345678", "201112345678"],
  "consent": true,
  "quiet_start": "20:00",
  "quiet_end": "07:00"
}

→ 201 {"data":{"id":12,"queued":2,"skipped":[]}}

How do I set auto-replies and read the inbox?

A rule is a keyword and a reply: match=contains (default) replies when the message contains the keyword, match=exact when it matches exactly. hands_off=1 marks the conversation Waiting for staff in the inbox. Rules also show on the Chatbot tab, and incoming messages in the Inbox tab.

curl -X POST https://sog.sog.eg/api/whatsapp/chatbot/rules \
  -H "Accept: application/json" \
  -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
  -d keyword="price" -d match=contains \
  -d reply="Our plans start at 60 USD a year: https://sog.eg/pricing" \
  -d hands_off=0

What do the error codes mean?

Every error returns a message explaining it, usually with a stable code your app can act on:

HTTP`code`Cause and fix
401invalid_keysWrong or rotated keys. Copy them from the Link API tab.
403subscription_inactiveThe package subscription is not active or has ended. Pay the renewal invoice.
403terms_requiredThe Number linking terms have not been accepted yet.
403feature_disabledYour package does not include the feature; the feature field names it.
403quota_exceededYou reached the message, template, campaign or app limit; the response may include an upgrade suggestion.
403device_limit / apps_limitMore active devices or apps than the package allows.
403opted_outThe recipient asked to stop receiving messages.
403client_frozen / sending_disabledSending is stopped on your account or paused on the platform. Contact support.
404not_foundThe message, template or campaign is not in your account.
409device_offlineNo number is Connected. Link the number again.
422invalid_phone and othersA field is missing or invalid; validation errors come per field in errors.
429rate_limitedYou sent faster than the minimum seconds between messages, or went over 60 requests a minute. Wait and retry.
502engine_unavailableA temporary sending fault. Retry shortly with the same Idempotency-Key.
{
  "message": "Message limit reached.",
  "code": "quota_exceeded",
  "upgrade": { "…": "suggested package" }
}

My account is on the older whatsapp.sog.eg platform. How do I send?

Existing customers on whatsapp.sog.eg stay there until they are moved to the portal step by step, and its endpoints differ. Use the account Auth Key and the app App Key from that dashboard, and send to https://whatsapp.sog.eg/api/create-message.

  • Fields: authkey, appkey, to (digits only, up to 13) and message (up to 1,000 characters), or template_id with variables named exactly as in the template, such as {name}.
  • Files: file is a public link to a jpg, png, webp, pdf, docx, xlsx, csv or txt file.
  • Status: POST /api/message-status with message_id returns pending, sent, delivered, read or error.
  • Webhook: set its URL in the device settings; it arrives within about a minute with payload, sender and receiver, and only counts as delivered when your server answers 200.
curl -X POST https://whatsapp.sog.eg/api/create-message \
  -H "Accept: application/json" \
  -d authkey=YOUR_AUTH_KEY \
  -d appkey=YOUR_APP_KEY \
  -d to=201012345678 \
  -d message="Hello from Example Store" \
  -d file=https://example.com/files/menu.pdf

# → 200 {"message_status":"Success","data":{"from":"2010…","to":"201012345678",
#        "status_code":200,"message_id":"3EB0…"}}

Common questions

The portal API endpoints send to individual numbers only, through the to field.

Send a stable Idempotency-Key header per message, such as the order number. If the request arrives twice and the first succeeded, you get the same response and no second copy is sent.

In the portal you follow sent or failed per message with /messages/{id}, and get a message.sent event by webhook. Delivered and read statuses are available on the older whatsapp.sog.eg platform only.

Ready to start?

WhatsApp API reference: every endpoint, field and error code

Open my API keys