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.
Integration flow
Four steps from zero to a sent invoice
- 1
Create an instance
POST /instances creates one on WhatsApp, Telegram or MAX and returns its idInstance and a one-time token.
- 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
Send messages
Once the instance is CONNECTED, send text, PDFs, images and group mentions with your API key (or the instance token).
- 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_INSTANCEReplace 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.
| Capability | Telegram (Beta) | MAX (Beta) | |
|---|---|---|---|
| Login | QR code or pairing code | Bot token | Bot token |
| Connection type | Unofficial linked device: numbers can be restricted | Official Bot API | Official bot API |
| Text and replies (quotes) | yes | yes (4096 characters) | yes (4000 characters) |
| Files (document, image, video, audio, voice) | yes | yes | yes (two-step upload, handled for you) |
| Location, contact card | yes | yes (a contact needs a phone number) | yes |
| Poll | yes | yes (max 10 options) | no |
| Reaction | yes | yes | no |
| Forward, edit, delete a sent message | yes | yes | yes |
| Typing indicator | yes | yes | yes (numeric chat id) |
| Mentions in groups | yes, resolved against the member list | yes: @username or numeric user id (real entities) | no |
| Group info | yes | yes (administrators only: a bot cannot list every member) | yes |
| Group management | full | rename, description, permissions, remove, promote, demote, leave, picture; cannot create groups or add people | rename, leave |
| Delivered / read receipts | yes | no: messages stay at Sent | no: messages stay at Sent |
Read marks (readChat) | yes | no | no |
| Phone checks, stories, catalog, pairing code | yes | no | no |
| Who the account can message | anyone, subject to WhatsApp rules | only people who messaged the bot first | only people who started the bot |
| Receiving | live connection | long polling or webhook | long 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.
/instancesCreate an instance: { name, channel?: WHATSAPP, TELEGRAM or MAX } (returns its API token once)ADMINinstances:writeLive/instancesList instances and their live statusVIEWERinstances:readLive/instances/{id}Get one instanceVIEWERinstances:readLive/instances/{id}/capabilitiesWhat the instance's channel can do (login method, file types, mentions, receipts)VIEWERinstances:readLive/instances/{id}/connectStart the session. WhatsApp: shows a QR code. Telegram and MAX: send { botToken }MEMBERinstances:writeLive/instances/{id}/qrCurrent QR code as a PNG data URLMEMBERinstances:readLive/instances/{id}/pairing-codeLink by phone number instead of a QR scanMEMBERinstances:writeLive, phone check/instances/{id}/rebootRestart the session without losing the linkMEMBERinstances:writeLive/instances/{id}/disconnectStop the session, keep credentialsMEMBERinstances:writeLive/instances/{id}/logoutUnlink the number and wipe stored credentialsADMINinstances:writeLive/instances/{id}/token/rotateIssue a new instance API tokenADMINinstances:writeLive/instances/{id}/eventsActivity logVIEWERinstances:readLive/instances/{id}Delete the instanceADMINinstances:writeLiveSending
(11)
Send from the connected number. Every send is queued, paced and idempotent. A 202 means accepted, not delivered.
/instances/{id}/messages/textSend a text message (supports replies and mentions)MEMBERmessages:sendLive/instances/{id}/messages/fileSend a PDF, document, image, video or audio from a URL or an uploadMEMBERmessages:sendLive, phone check/instances/{id}/messages/locationSend a locationMEMBERmessages:sendLive, phone check/instances/{id}/messages/contactSend a contact cardMEMBERmessages:sendLive, phone check/instances/{id}/messages/pollSend a pollMEMBERmessages:sendLive, phone check/instances/{id}/messages/reactionReact to a messageMEMBERmessages:sendLive, phone check/instances/{id}/messages/forwardForward a message (text and received media)MEMBERmessages:sendLive, phone check/instances/{id}/messages/{messageId}Edit a text message you sentMEMBERmessages:sendLive, phone check/instances/{id}/messages/{messageId}Delete a message for everyoneMEMBERmessages:sendLive, phone check/instances/{id}/chats/typingShow composing / recording / pausedMEMBERmessages:sendLive, phone check/instances/{id}/chats/readMark a chat as readMEMBERmessages:sendLive, phone checkGroups & mentions
(9)
Message groups and tag members with real mention notifications. Mentions are resolved against the real member list.
/instances/{id}/groupsList groupsVIEWERmessages:readLive, phone check/instances/{id}/groups/{groupId}Group detailsVIEWERmessages:readLive, phone check/instances/{id}/groups/{groupId}/participantsMembers with phone, lid and mentionAsVIEWERmessages:readLive, phone check/instances/{id}/groupsCreate a groupMEMBERmessages:sendLive, phone check/instances/{id}/groups/{groupId}Rename, change description or settingsMEMBERmessages:sendLive, phone check/instances/{id}/groups/{groupId}/participantsAdd, remove, promote or demote participantsMEMBERmessages:sendLive, phone check/instances/{id}/groups/{groupId}/pictureSet the group pictureMEMBERmessages:sendLive, phone check/instances/{id}/groups/{groupId}/leaveLeave the groupMEMBERmessages:sendLive, phone check/instances/{id}/groups/{groupId}/messagesSend to a group and tag membersMEMBERmessages:sendLive, phone checkReceiving & journals
(8)
Read what was sent and received. Incoming messages are stored and also pushed to the notification queue and webhooks.
/instances/{id}/messagesMessage history with filters (chat, direction, status, externalRef)VIEWERmessages:readLive/instances/{id}/messages/{messageId}One message with its status historyVIEWERmessages:readLive/instances/{id}/messages/last-incomingRecent incoming messagesVIEWERmessages:readLive/instances/{id}/messages/last-outgoingRecent outgoing messagesVIEWERmessages:readLive/instances/{id}/messages/{messageId}/fileDownload a received fileMEMBERmessages:readLive, phone check/instances/{id}/chatsChats with stored messagesVIEWERmessages:readLive/instances/{id}/notifications/nextPoll the next notification (receive)MEMBERmessages:readLive/instances/{id}/notifications/{receiptId}Acknowledge (delete) a notificationMEMBERmessages:sendLiveQueue, state & settings
(8)
Inspect and control the outgoing queue, connection state and per-number settings.
/instances/{id}/queueMessages waiting to be sentVIEWERmessages:readLive/instances/{id}/queue/countQueue and webhook countsVIEWERmessages:readLive/instances/{id}/queueCancel waiting messagesADMINmessages:sendLive/instances/{id}/queue/webhooksClear pending webhook deliveriesADMINmessages:sendLive/instances/{id}/stateConnection status and phone numberVIEWERinstances:readLive/instances/{id}/state/historyConnection historyVIEWERinstances:readLive/instances/{id}/settingsDelay, daily limit, read-receipt and webhook togglesVIEWERinstances:readLive/instances/{id}/settingsChange those settingsADMINinstances:writeLiveWebhooks & opt-outs
(11)
Signed event delivery with retries and a delivery log, plus a workspace-wide do-not-message list.
/webhooksList webhooksVIEWERwebhooks:manageLive/webhooks/eventsValid event namesVIEWERwebhooks:manageLive/webhooksRegister an endpoint (secret shown once)ADMINwebhooks:manageLive/webhooks/{id}Update an endpointADMINwebhooks:manageLive/webhooks/{id}Remove an endpointADMINwebhooks:manageLive/webhooks/{id}/rotate-secretIssue a new signing secretADMINwebhooks:manageLive/webhooks/{id}/testSend a signed test eventADMINwebhooks:manageLive/webhooks/{id}/deliveriesDelivery log with attempts and status codesVIEWERwebhooks:manageLive/opt-outsList opted-out numbersVIEWERmessages:readLive/opt-outsAdd a number to the do-not-message listADMINmessages:sendLive/opt-outs/{phone}Remove a numberADMINmessages:sendLiveContacts & service methods
(4)
Look people up and read profile details.
/instances/{id}/contactsSynced contactsVIEWERmessages:readLive, phone check/instances/{id}/contacts/checkCheck which numbers are on WhatsAppMEMBERmessages:sendLive, phone check/instances/{id}/contacts/{chatId}/avatarProfile picture URLMEMBERmessages:readLive, phone check/instances/{id}/contacts/{chatId}/infoContact detailsMEMBERmessages:readLive, phone checkStatuses (stories)
(4)
Post and manage WhatsApp statuses. Recipients default to your synced contacts (max 500). View statistics are not available.
/instances/{id}/statuses/textPost a text statusMEMBERmessages:sendLive, phone check/instances/{id}/statuses/mediaPost an image, video or voice status (multipart)MEMBERmessages:sendLive, phone check/instances/{id}/statusesList statuses (direction IN or OUT)VIEWERmessages:readLive, phone check/instances/{id}/statuses/{messageId}Delete a statusMEMBERmessages:sendLive, phone checkBusiness catalog
(6)
WhatsApp Business accounts only. Reads and product writes work; collection writes, SendProduct and SendOrder are not available.
/instances/{id}/catalog/productsList productsVIEWERmessages:readLive, phone check/instances/{id}/catalog/productsCreate a productMEMBERmessages:sendLive, phone check/instances/{id}/catalog/products/{productId}Edit a product (full product required)MEMBERmessages:sendLive, phone check/instances/{id}/catalog/productsDelete productsMEMBERmessages:sendLive, phone check/instances/{id}/catalog/collectionsList collectionsVIEWERmessages:readLive, phone check/instances/{id}/catalog/orders/{orderId}Order detailsVIEWERmessages:readLive, phone checkAPI 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.
/apikeysList keys: prefix, scopes, last used, expiry, status. Also returns the available scopesADMINsession onlyLive/apikeysCreate a key: { name, scopes[], expiresInDays? }. The full key is returned onceADMINsession onlyLive/apikeys/{id}Revoke a key (immediate)ADMINsession onlyLiveNotifications
(6)
The in-app bell. Also delivered live over the Socket.IO connection as a notification event.
/notificationsList notifications (cursor pagination, unreadOnly)VIEWERsession onlyLive/notifications/unread-countUnread count for the bellVIEWERsession onlyLive/notifications/{id}/readMark one readVIEWERsession onlyLive/notifications/read-allMark all readVIEWERsession onlyLive/notifications/preferencesEmail preferences (security emails are always on)VIEWERsession onlyLive/notifications/preferencesChange instance, support and billing email preferencesVIEWERsession onlyLiveSupport tickets
(6)
Open and follow tickets (SJ-1001 upward). Staff replies appear as "Sendjade Support"; internal notes are never shown to you.
/support/ticketsOpen a ticket: { subject, category?, priority?, body } (10 per hour)MEMBERsession onlyLive/support/ticketsYour workspace's ticketsVIEWERsession onlyLive/support/tickets/{id}A ticket and its conversationVIEWERsession onlyLive/support/tickets/{id}/messagesReply: { body }MEMBERsession onlyLive/support/tickets/{id}/closeClose a ticketMEMBERsession onlyLive/support/tickets/{id}/reopenReopen a ticketMEMBERsession onlyLiveBilling (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.
/billing/walletBalance, currency (USD) and low-balance thresholdVIEWERbilling:readLive/billing/transactionsTransactions with type and date filters (credits, debits, adjustments, refunds)VIEWERbilling:readLiveGreen-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 itselfmessage.acceptedWhatsApp accepted an API message for deliverymessage.deliveredDelivered to the recipient's device, when WhatsApp reports itmessage.readRead by the recipient, when WhatsApp reports itmessage.failedSending failed (with an error code)instance.stateThe connection status changedgroup.updatedA group changed (name, settings, participants)webhook.testSent by the Test button to check your endpointConventions
Predictable by design
Errors
{ "error": { "code": "not_found", "message": "Instance not found" } } // native
{ "message": "Unauthorized: wrong idInstance or apiTokenInstance", "code": "unauthorized" } // Green-styleStatuses
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.