Developers

Integrate Sendjade in an afternoon

One REST API for WhatsApp, Telegram and MAX, with scoped API keys, a Green-API-compatible API, idempotent sends, signed webhooks and real group mentions. Your app never touches sockets or QR handling.

Heads up: WhatsApp-side behaviour has not yet been verified on a real number. Test in the Sandbox with a spare number first. Telegram and MAX are in Beta (see Channels). Hostnames on this page are illustrative until your deployment is live.

Integration flow

Four steps from zero to a sent invoice

  1. 1

    Create an instance

    POST /instances creates one on WhatsApp, Telegram or MAX and returns its idInstance and a one-time token.

  2. 2

    Connect it

    WhatsApp: POST /connect, then show the QR from GET /qr. Telegram or MAX: POST /connect with a bot token. No QR.

  3. 3

    Send messages

    Once the instance is CONNECTED, send text, PDFs, images and group mentions with your API key (or the instance token).

  4. 4

    React to events

    Signed webhooks, or a polling queue, tell you about incoming messages, delivery, read receipts and failures.

Quick start

Create an instance, scan the QR, send a PDF

  • Authenticate with a scoped, revocable API key: Authorization: Bearer sjk_...
  • Or use the Green-API-compatible URL with only the instance id and token
  • JSON in, JSON out, with a consistent error format
  • Idempotency keys, so retries never double-send
  • Group @mentions resolved against the real member list
BASE=https://api.sendjade.com/api/v1
# export SENDJADE_API_KEY=sjk_...      (Console > API keys. Scopes: instances:write, instances:read, messages:send)

# 1. Create an instance (scope instances:write). Save instance.id, instance.idInstance and apiToken: the token is shown once.
curl -s -X POST $BASE/instances -H "Authorization: Bearer $SENDJADE_API_KEY" \
  -H "Content-Type: application/json" -d '{"name":"Adaeze Bakery"}'

# 2. Connect, then fetch the QR code (PNG data URL, scope instances:read) and scan it in WhatsApp > Linked devices
curl -s -X POST $BASE/instances/$INSTANCE_UUID/connect -H "Authorization: Bearer $SENDJADE_API_KEY"
curl -s $BASE/instances/$INSTANCE_UUID/qr -H "Authorization: Bearer $SENDJADE_API_KEY"

# 3. Send text (scope messages:send). 202 means "accepted for sending", not "delivered".
curl -s -X POST $BASE/instances/$INSTANCE_UUID/messages/text -H "Authorization: Bearer $SENDJADE_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: order-1042-text" \
  -d '{"chatId":"2348012345678","text":"Hello from Sendjade"}'

# 4. Send a PDF invoice by URL (arrives as a real attachment)
curl -s -X POST $BASE/instances/$INSTANCE_UUID/messages/file -H "Authorization: Bearer $SENDJADE_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: invoice-1042" \
  -d '{"chatId":"2348012345678","url":"https://files.example.com/inv-1042.pdf","fileName":"Invoice-1042.pdf","caption":"Your invoice is attached. Due Friday."}'

# 5. Message a group and tag two members (real mentions)
curl -s -X POST $BASE/instances/$INSTANCE_UUID/groups/$GROUP_ID/messages -H "Authorization: Bearer $SENDJADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"@2348012345678 @2348098765432 please review the stock count","mentions":["2348012345678","2348098765432"]}'

# Telegram or MAX: create with {"name":"Orders bot","channel":"TELEGRAM"}, connect with {"botToken":"..."} (no QR),
# and use the numeric chat id as chatId.
# Simple tools can use the Green-style URL instead: POST https://api.sendjade.com/waInstance$ID_INSTANCE/sendMessage/$API_TOKEN_INSTANCE

Replace the host with your deployment and the SENDJADE_* values with your own. Never commit tokens to code.

Channels

One API, three channels

Choose the channel when you create the instance: { "name": "...", "channel": "WHATSAPP" | "TELEGRAM" | "MAX" }. Telegram and MAX connect with a bot token (POST /instances/{id}/connect with { "botToken": "..." }) and have no QR code. Queue, idempotency, opt-outs, webhooks and roles are identical on all three. Anything a channel cannot do answers 422 not_supported_on_channel; GET /instances/{id}/capabilities tells you in advance.

CapabilityWhatsAppTelegram (Beta)MAX (Beta)
LoginQR code or pairing codeBot tokenBot token
Connection typeUnofficial linked device: numbers can be restrictedOfficial Bot APIOfficial bot API
Text and replies (quotes)yesyes (4096 characters)yes (4000 characters)
Files (document, image, video, audio, voice)yesyesyes (two-step upload, handled for you)
Location, contact cardyesyes (a contact needs a phone number)yes
Pollyesyes (max 10 options)no
Reactionyesyesno
Forward, edit, delete a sent messageyesyesyes
Typing indicatoryesyesyes (numeric chat id)
Mentions in groupsyes, resolved against the member listyes: @username or numeric user id (real entities)no
Group infoyesyes (administrators only: a bot cannot list every member)yes
Group managementfullrename, description, permissions, remove, promote, demote, leave, picture; cannot create groups or add peoplerename, leave
Delivered / read receiptsyesno: messages stay at Sentno: messages stay at Sent
Read marks (readChat)yesnono
Phone checks, stories, catalog, pairing codeyesnono
Who the account can messageanyone, subject to WhatsApp rulesonly people who messaged the bot firstonly people who started the bot
Receivinglive connectionlong polling or webhooklong polling or webhook

Setup steps for a Telegram bot and a MAX bot, chat ids, receiving modes and limits are on the Channels documentation.

API reference

Native REST endpoints

Paths are relative to https://api.sendjade.com/api/v1. Authenticate with a workspace API key (Authorization: Bearer sjk_...) or a session. Each row shows the minimum role and the API-key scope it needs; session only routes (account, support, notifications, key management) refuse API keys. Live is built and tested with a simulated connection; Live, phone check is built but only a real number can prove the WhatsApp side; Not implemented is deliberately absent. See Authentication for scopes.

Instances

(13)

An instance is one connected account: a WhatsApp number, or a Telegram or MAX bot. Create it, connect it, and manage its session.

POST/instancesCreate an instance: { name, channel?: WHATSAPP, TELEGRAM or MAX } (returns its API token once)ADMINinstances:writeLive
GET/instancesList instances and their live statusVIEWERinstances:readLive
GET/instances/{id}Get one instanceVIEWERinstances:readLive
GET/instances/{id}/capabilitiesWhat the instance's channel can do (login method, file types, mentions, receipts)VIEWERinstances:readLive
POST/instances/{id}/connectStart the session. WhatsApp: shows a QR code. Telegram and MAX: send { botToken }MEMBERinstances:writeLive
GET/instances/{id}/qrCurrent QR code as a PNG data URLMEMBERinstances:readLive
POST/instances/{id}/pairing-codeLink by phone number instead of a QR scanMEMBERinstances:writeLive, phone check
POST/instances/{id}/rebootRestart the session without losing the linkMEMBERinstances:writeLive
POST/instances/{id}/disconnectStop the session, keep credentialsMEMBERinstances:writeLive
POST/instances/{id}/logoutUnlink the number and wipe stored credentialsADMINinstances:writeLive
POST/instances/{id}/token/rotateIssue a new instance API tokenADMINinstances:writeLive
GET/instances/{id}/eventsActivity logVIEWERinstances:readLive
DELETE/instances/{id}Delete the instanceADMINinstances:writeLive

Sending

(11)

Send from the connected number. Every send is queued, paced and idempotent. A 202 means accepted, not delivered.

POST/instances/{id}/messages/textSend a text message (supports replies and mentions)MEMBERmessages:sendLive
POST/instances/{id}/messages/fileSend a PDF, document, image, video or audio from a URL or an uploadMEMBERmessages:sendLive, phone check
POST/instances/{id}/messages/locationSend a locationMEMBERmessages:sendLive, phone check
POST/instances/{id}/messages/contactSend a contact cardMEMBERmessages:sendLive, phone check
POST/instances/{id}/messages/pollSend a pollMEMBERmessages:sendLive, phone check
POST/instances/{id}/messages/reactionReact to a messageMEMBERmessages:sendLive, phone check
POST/instances/{id}/messages/forwardForward a message (text and received media)MEMBERmessages:sendLive, phone check
PATCH/instances/{id}/messages/{messageId}Edit a text message you sentMEMBERmessages:sendLive, phone check
DELETE/instances/{id}/messages/{messageId}Delete a message for everyoneMEMBERmessages:sendLive, phone check
POST/instances/{id}/chats/typingShow composing / recording / pausedMEMBERmessages:sendLive, phone check
POST/instances/{id}/chats/readMark a chat as readMEMBERmessages:sendLive, phone check

Groups & mentions

(9)

Message groups and tag members with real mention notifications. Mentions are resolved against the real member list.

GET/instances/{id}/groupsList groupsVIEWERmessages:readLive, phone check
GET/instances/{id}/groups/{groupId}Group detailsVIEWERmessages:readLive, phone check
GET/instances/{id}/groups/{groupId}/participantsMembers with phone, lid and mentionAsVIEWERmessages:readLive, phone check
POST/instances/{id}/groupsCreate a groupMEMBERmessages:sendLive, phone check
PATCH/instances/{id}/groups/{groupId}Rename, change description or settingsMEMBERmessages:sendLive, phone check
POST/instances/{id}/groups/{groupId}/participantsAdd, remove, promote or demote participantsMEMBERmessages:sendLive, phone check
POST/instances/{id}/groups/{groupId}/pictureSet the group pictureMEMBERmessages:sendLive, phone check
POST/instances/{id}/groups/{groupId}/leaveLeave the groupMEMBERmessages:sendLive, phone check
POST/instances/{id}/groups/{groupId}/messagesSend to a group and tag membersMEMBERmessages:sendLive, phone check

Receiving & journals

(8)

Read what was sent and received. Incoming messages are stored and also pushed to the notification queue and webhooks.

GET/instances/{id}/messagesMessage history with filters (chat, direction, status, externalRef)VIEWERmessages:readLive
GET/instances/{id}/messages/{messageId}One message with its status historyVIEWERmessages:readLive
GET/instances/{id}/messages/last-incomingRecent incoming messagesVIEWERmessages:readLive
GET/instances/{id}/messages/last-outgoingRecent outgoing messagesVIEWERmessages:readLive
GET/instances/{id}/messages/{messageId}/fileDownload a received fileMEMBERmessages:readLive, phone check
GET/instances/{id}/chatsChats with stored messagesVIEWERmessages:readLive
GET/instances/{id}/notifications/nextPoll the next notification (receive)MEMBERmessages:readLive
DELETE/instances/{id}/notifications/{receiptId}Acknowledge (delete) a notificationMEMBERmessages:sendLive

Queue, state & settings

(8)

Inspect and control the outgoing queue, connection state and per-number settings.

GET/instances/{id}/queueMessages waiting to be sentVIEWERmessages:readLive
GET/instances/{id}/queue/countQueue and webhook countsVIEWERmessages:readLive
DELETE/instances/{id}/queueCancel waiting messagesADMINmessages:sendLive
DELETE/instances/{id}/queue/webhooksClear pending webhook deliveriesADMINmessages:sendLive
GET/instances/{id}/stateConnection status and phone numberVIEWERinstances:readLive
GET/instances/{id}/state/historyConnection historyVIEWERinstances:readLive
GET/instances/{id}/settingsDelay, daily limit, read-receipt and webhook togglesVIEWERinstances:readLive
PATCH/instances/{id}/settingsChange those settingsADMINinstances:writeLive

Webhooks & opt-outs

(11)

Signed event delivery with retries and a delivery log, plus a workspace-wide do-not-message list.

GET/webhooksList webhooksVIEWERwebhooks:manageLive
GET/webhooks/eventsValid event namesVIEWERwebhooks:manageLive
POST/webhooksRegister an endpoint (secret shown once)ADMINwebhooks:manageLive
PATCH/webhooks/{id}Update an endpointADMINwebhooks:manageLive
DELETE/webhooks/{id}Remove an endpointADMINwebhooks:manageLive
POST/webhooks/{id}/rotate-secretIssue a new signing secretADMINwebhooks:manageLive
POST/webhooks/{id}/testSend a signed test eventADMINwebhooks:manageLive
GET/webhooks/{id}/deliveriesDelivery log with attempts and status codesVIEWERwebhooks:manageLive
GET/opt-outsList opted-out numbersVIEWERmessages:readLive
POST/opt-outsAdd a number to the do-not-message listADMINmessages:sendLive
DELETE/opt-outs/{phone}Remove a numberADMINmessages:sendLive

Contacts & service methods

(4)

Look people up and read profile details.

GET/instances/{id}/contactsSynced contactsVIEWERmessages:readLive, phone check
POST/instances/{id}/contacts/checkCheck which numbers are on WhatsAppMEMBERmessages:sendLive, phone check
GET/instances/{id}/contacts/{chatId}/avatarProfile picture URLMEMBERmessages:readLive, phone check
GET/instances/{id}/contacts/{chatId}/infoContact detailsMEMBERmessages:readLive, phone check

Statuses (stories)

(4)

Post and manage WhatsApp statuses. Recipients default to your synced contacts (max 500). View statistics are not available.

POST/instances/{id}/statuses/textPost a text statusMEMBERmessages:sendLive, phone check
POST/instances/{id}/statuses/mediaPost an image, video or voice status (multipart)MEMBERmessages:sendLive, phone check
GET/instances/{id}/statusesList statuses (direction IN or OUT)VIEWERmessages:readLive, phone check
DELETE/instances/{id}/statuses/{messageId}Delete a statusMEMBERmessages:sendLive, phone check

Business catalog

(6)

WhatsApp Business accounts only. Reads and product writes work; collection writes, SendProduct and SendOrder are not available.

GET/instances/{id}/catalog/productsList productsVIEWERmessages:readLive, phone check
POST/instances/{id}/catalog/productsCreate a productMEMBERmessages:sendLive, phone check
PATCH/instances/{id}/catalog/products/{productId}Edit a product (full product required)MEMBERmessages:sendLive, phone check
DELETE/instances/{id}/catalog/productsDelete productsMEMBERmessages:sendLive, phone check
GET/instances/{id}/catalog/collectionsList collectionsVIEWERmessages:readLive, phone check
GET/instances/{id}/catalog/orders/{orderId}Order detailsVIEWERmessages:readLive, phone check

API keys

(3)

Workspace-scoped keys for your servers (sjk_...). Shown once, revocable, with a last-used record. Keys cannot manage keys: use a signed-in session.

GET/apikeysList keys: prefix, scopes, last used, expiry, status. Also returns the available scopesADMINsession onlyLive
POST/apikeysCreate a key: { name, scopes[], expiresInDays? }. The full key is returned onceADMINsession onlyLive
DELETE/apikeys/{id}Revoke a key (immediate)ADMINsession onlyLive

Notifications

(6)

The in-app bell. Also delivered live over the Socket.IO connection as a notification event.

GET/notificationsList notifications (cursor pagination, unreadOnly)VIEWERsession onlyLive
GET/notifications/unread-countUnread count for the bellVIEWERsession onlyLive
POST/notifications/{id}/readMark one readVIEWERsession onlyLive
POST/notifications/read-allMark all readVIEWERsession onlyLive
GET/notifications/preferencesEmail preferences (security emails are always on)VIEWERsession onlyLive
PATCH/notifications/preferencesChange instance, support and billing email preferencesVIEWERsession onlyLive

Support tickets

(6)

Open and follow tickets (SJ-1001 upward). Staff replies appear as "Sendjade Support"; internal notes are never shown to you.

POST/support/ticketsOpen a ticket: { subject, category?, priority?, body } (10 per hour)MEMBERsession onlyLive
GET/support/ticketsYour workspace's ticketsVIEWERsession onlyLive
GET/support/tickets/{id}A ticket and its conversationVIEWERsession onlyLive
POST/support/tickets/{id}/messagesReply: { body }MEMBERsession onlyLive
POST/support/tickets/{id}/closeClose a ticketMEMBERsession onlyLive
POST/support/tickets/{id}/reopenReopen a ticketMEMBERsession onlyLive

Billing (US dollars only)

(2)

Wallet balance and transactions, always in USD. Online payments are not enabled yet: contact support to top up. Reads work with an API key that has billing:read.

GET/billing/walletBalance, currency (USD) and low-balance thresholdVIEWERbilling:readLive
GET/billing/transactionsTransactions with type and date filters (credits, debits, adjustments, refunds)VIEWERbilling:readLive

Green-API-compatible

Switch an existing integration by changing the base URL

Server-to-server calls use https://api.sendjade.com/waInstance{idInstance}/{method}/{apiTokenInstance}. The instance id and token are in the URL (no auth header), method names are case-insensitive, and request and response field names follow Green API. Wrong credentials return the same 401 for unknown ids and wrong tokens. They work for instances of every channel. These are the methods that work, grouped as in Green API. Read the migration guide.

Account

qrgetSettingssetSettingsgetStateInstancegetStateInstanceHistorygetWaSettingsrebootlogoutgetAuthorizationCodesetProfilePicture

Sending

sendMessagesendFileByUrlsendFileByUploadsendLocationsendContactsendPollforwardMessagessendReaction

Receiving

receiveNotificationdeleteNotificationdownloadFile

Journals

getChatHistorygetMessagelastIncomingMessageslastOutgoingMessages

Queue

showMessagesQueuegetMessagesCountclearMessagesQueuegetWebhooksCountclearWebhooksQueue

Groups

createGroupgetGroupDataupdateGroupNameupdateGroupSettingsaddGroupParticipantremoveGroupParticipantsetGroupAdminremoveAdminsetGroupPictureleaveGroup

Statuses

sendTextStatussendMediaStatussendVoiceStatusgetOutgoingStatusesgetIncomingStatusesdeleteStatus

Read mark & messages

readChatsendTypingeditMessagedeleteMessage

Service

checkWhatsappgetAvatargetContactInfogetContactsgetChatsgetAllowedReactions

Honest scope

Not implemented, and why

These return 501 not_implemented on Green-style routes (or are simply absent), so you can plan around them.

  • UploadFileSendjade does not host files. Use SendFileByUpload, or host the file yourself and use SendFileByUrl.
  • SendInteractiveButtons / SendInteractiveButtonsReplyWhatsApp does not deliver interactive buttons reliably over unofficial connections. Use polls or numbered text replies instead.
  • LastIncomingCalls / LastOutgoingCallsCall events are not recorded yet.
  • ArchiveChat / UnarchiveChat / SetDisappearingChatNot implemented yet.
  • AddContact / EditContact / DeleteContactAddress-book editing is not exposed through the unofficial connection yet.
  • GetStatusStatisticStatus view counts are not collected.
  • SendProduct, SendOrder, collection create / edit / delete / moveThe underlying library offers no write API for them. Catalog reads and product writes are on the native API only.
  • Partner methods (GetInstances, CreateInstance, DeleteInstanceAccount)They need partner-level provisioning keys, which are not built. Workspace API keys exist, and can create instances in their own workspace through the native API.
  • Online payments, and charging messages against the walletPayments need a payment-gateway account, which is the owner's decision. Plans are a flat price per instance, and wallet credits are made by Sendjade staff today.
  • Delivered / read receipts on Telegram and MAXThose platforms do not give bots receipts, so messages stay at SENT. See the channel matrix above.

Webhooks

Know the moment something changes

Register a public HTTPS endpoint and receive JSON events. Each request carries X-Sendjade-Signature: t=<unix>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw body>" with your webhook secret. Failed deliveries are retried 6 times with exponential backoff and listed in the delivery log. Prefer not to expose a URL? Poll the notification queue instead. Webhook guide.

message.receivedAn incoming message (text, file, location, contact, poll or reaction)
message.sent_from_phoneA message you sent from the phone itself
message.acceptedWhatsApp accepted an API message for delivery
message.deliveredDelivered to the recipient's device, when WhatsApp reports it
message.readRead by the recipient, when WhatsApp reports it
message.failedSending failed (with an error code)
instance.stateThe connection status changed
group.updatedA group changed (name, settings, participants)
webhook.testSent by the Test button to check your endpoint

Conventions

Predictable by design

Errors

{ "error": { "code": "not_found", "message": "Instance not found" } }   // native
{ "message": "Unauthorized: wrong idInstance or apiTokenInstance", "code": "unauthorized" }   // Green-style

Statuses

An instance is CREATED, QR_PENDING, CONNECTING, CONNECTED, DISCONNECTED, LOGGED_OUT or FAILED. Messages move through QUEUED, PROCESSING, SENT, DELIVERED, READ or FAILED. An API success means accepted for sending, not delivered. On Telegram and MAX messages stay at SENT.

Partner API

Software platforms that run WhatsApp for many shops use the separate Partner API (beta): shops, embedded QR, one signed webhook and per-message usage records. Download the OpenAPI spec.

Safety

Sends are queued and paced per number, capped per 24 hours, refused for opted-out recipients, and safe to retry with an Idempotency-Key. File URLs are fetched with SSRF protection.

Security

API keys and instance tokens are hashed at rest and shown once, sessions and bot tokens are encrypted with AES-256-GCM, and every request is scoped to your workspace. Another workspace’s ids always answer 404.

Currency

Wallet balances and prices are in US dollars (USD) only.

Start sending from your own number

Create a free account, connect a spare number and send your first message in minutes.