Gupshup WhatsApp API
Gupshup self-serve WhatsApp API: templates, text, media, buttons, lists, OTP templates and user blocking with one API key.
CommunicationGuided#whatsapp#messaging#templates#otp#india#chatbot
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Gupshup is a conversational messaging platform with a large base of Indian businesses. Its WhatsApp Self-Serve Platform lets you onboard a WhatsApp Business number yourself (through Meta's Embedded Signup), pay per use from a prepaid wallet and send messages through a simple REST API on api.gupshup.io. This guided collection covers that self-serve API: checking your app, listing approved templates, sending session messages (text, image, quick-reply buttons, list, call-to-action URL) inside the 24-hour customer-service window, sending template messages (text, image, authentication/OTP) at any time, and blocking abusive users.
Get credentials
- Sign up or log in at gupshup.io (Google, Facebook or GitHub sign-in work too). One Gupshup account per email address.
- From Dashboard > WhatsApp, choose Create your first app and give it a unique name of at least six characters with no spaces; this is the
src.name(appName) the API needs. Unused apps are deleted after 60 days. See Create your first app. - Go live by connecting a phone number with Meta's Embedded Signup (onboarding guide), or try the shared sandbox number first (sandbox).
- In the app's Settings tab copy the App ID into
appIdand the App API Key intoapiKey. Put the app's WhatsApp number (country code, no plus) intosourceNumber. - Recharge the wallet: messages are charged from it (1 credit = 1 USD).
Authentication and base URL
Every call sends the key in an apikey header; this collection sets it once. Base URL: https://api.gupshup.io. Calls must come from your server: the send API refuses browser (AJAX) calls, and the key must never ship in front-end code. The send endpoints take form-urlencoded bodies in which message or template is a JSON string.
The 24-hour rule
WhatsApp lets you send free-form session messages (folder 2) only within 24 hours of the user's last message to you. Outside that window, or to start a conversation, send an approved template (folder 3). Templates are created and approved (by Meta) in the dashboard's Templates tab; use the List templates request to get their IDs.
Variables and run order
Fill apiKey, appId, appName, sourceNumber and destination (your own WhatsApp number for testing). Run 1. Start here (it saves an approved template ID into templateId), then send a template from 3. Template messages; reply to it from your phone to open the 24-hour window, then try 2. Session messages. Delivery statuses (enqueued, sent, delivered, read, failed) arrive on the callback URL you set in the app's Webhooks tab, keyed by the returned messageId.
Limits and pricing
Gupshup charges a small per-message fee on top of Meta's per-message pricing (by category: marketing, utility, authentication, and by country); see your app's pricing in the dashboard and Meta's pricing page. Your number's messaging limit (unique users per 24 hours) is shown in Settings and grows with quality. The API answers 429 when you send too fast.
Common errors
| Response | Meaning | What to do |
|---|---|---|
401 Authentication Failed | Wrong or missing apikey | Copy the App API Key again. |
400 Invalid Destination | Bad recipient number | Country code + number, digits only. |
400 Invalid App Details | src.name and source do not match | Use the app name that owns the number. |
429 Too Many Requests | Rate limited | Back off and retry. |
Webhook failed, code 1003 | Wallet balance low | Recharge. |
Webhook failed, codes 1004-1008 | Session window closed / template mismatch or not opted in | Send an approved template. |
Webhook failed, 4003 / 4005 | Template did not match / template paused | Check the template ID, params and quality. |
Full list: error codes.
Links
- API reference: docs.gupshup.io/reference/msg
- Template messages: docs.gupshup.io/docs/template-messages
- Message events (webhooks): docs.gupshup.io/docs/message-events
- Getting started: docs.gupshup.io/docs/overview
Endpoints 13
1. Start here
- GETGet business details
/wa/app/{{appId}}/businessReturns the business profile stored for the app: name, contact, address, website, vertical and when it was created. It is a read-only call, so use it first to… - GETList templates
/wa/app/{{appId}}/templateLists the message templates of the app with their Gupshup template ID, name, category, type, language, status and quality. Filter to approved templates to see… - GETGet a template
/wa/app/{{appId}}/template/{{templateId}}Returns one template by its Gupshup template ID (templateId), including the body text with placeholders, buttons, category, status and quality rating. Check…
2. Session messages (24-hour window)
- POSTSend a text message
/wa/api/v1/msgSends a plain text message. Set previewUrl: true inside message to show a link preview for the first URL in the text. What comes back: status: submitted and a… - POSTSend an image
/wa/api/v1/msgSends an image from a public HTTPS URL with an optional caption. originalUrl is the full image and previewUrl the thumbnail (they can be the same URL).… - POSTSend quick-reply buttons
/wa/api/v1/msgSends a message with up to three quick-reply buttons. content holds the text (or a media header via content.type image/video/file with url), plus optional… - POSTSend a list message
/wa/api/v1/msgSends an interactive list: a header (title), body, a menu button (globalButtons) and sections (items) with up to ten rows in total. Each row has title,… - POSTSend a call-to-action URL button
/wa/api/v1/msgSends a message with one button that opens a URL, for example a payment or tracking page, with optional image or video header and footer. Use it instead of…
3. Template messages
- POSTSend a text template
/wa/api/v1/template/msgSends an approved text template. template.id is the Gupshup template ID (templateId, from List templates) and params are the variable values in order. Add… - POSTSend an image template
/wa/api/v1/template/msgSends an approved template whose header is an image. The image goes in a separate message form field: {"type":"image","image":{"link":"..."}} (or a media id… - POSTSend an authentication (OTP) template
/wa/api/v1/template/msgSends an approved authentication template carrying a one-time code, for login or payment confirmation. The code must appear twice in params: once for the body…
4. Users
- POSTBlock users
/wa/app/{{appId}}/user/blockBlocks one or more WhatsApp users from messaging your number. You can only block users who messaged you in the last 24 hours, and the block list holds up to… - GETList blocked users
/wa/app/{{appId}}/user/blocklistReturns the users your business has blocked, 100 at most per page. Use after with the cursor from the previous response to read the next page; useful for…
API details
- Base URL
https://api.gupshup.io- Authentication
- An API key in the apikey header
- Operations
- 13 operations on 13 pathsPOST 9GET 4
- Main resources
- 1. Start here 32. Session messages (24-hour window) 53. Template messages 34. Users 2
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-18 - Links
- Documentation
How to test the Gupshup WhatsApp API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Gupshup WhatsApp API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the apikey header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get business details” (GET /wa/app/{{appId}}/business), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Gupshup WhatsApp API?
Gupshup self-serve WhatsApp API: templates, text, media, buttons, lists, OTP templates and user blocking with one API key. It is listed under Communication and has 13 endpoints.
Who publishes the Gupshup WhatsApp API?
It is listed from Gupshup's public API description (an OpenAPI document), not published by Gupshup on Swastik Codes. Anyone who controls gupshup.io can claim the profile by adding a DNS TXT record.
What is the base URL of the Gupshup WhatsApp API?
Requests go to https://api.gupshup.io. Endpoint paths are added to this base URL.
How do I authenticate with the Gupshup WhatsApp API?
With an API key in the apikey header.
How many endpoints does the Gupshup WhatsApp API have?
13 operations on 13 paths (9 POST, 4 GET). The largest groups are 1. Start here, 2. Session messages (24-hour window), 3. Template messages, 4. Users.
Is forking the Gupshup WhatsApp API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.