Gupshup

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

  1. Sign up or log in at gupshup.io (Google, Facebook or GitHub sign-in work too). One Gupshup account per email address.
  2. 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.
  3. Go live by connecting a phone number with Meta's Embedded Signup (onboarding guide), or try the shared sandbox number first (sandbox).
  4. In the app's Settings tab copy the App ID into appId and the App API Key into apiKey. Put the app's WhatsApp number (country code, no plus) into sourceNumber.
  5. 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

ResponseMeaningWhat to do
401 Authentication FailedWrong or missing apikeyCopy the App API Key again.
400 Invalid DestinationBad recipient numberCountry code + number, digits only.
400 Invalid App Detailssrc.name and source do not matchUse the app name that owns the number.
429 Too Many RequestsRate limitedBack off and retry.
Webhook failed, code 1003Wallet balance lowRecharge.
Webhook failed, codes 1004-1008Session window closed / template mismatch or not opted inSend an approved template.
Webhook failed, 4003 / 4005Template did not match / template pausedCheck the template ID, params and quality.

Full list: error codes.

Links

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

How to test the Gupshup WhatsApp API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Gupshup WhatsApp API collection, without the publisher's secrets.
  3. 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.
  4. 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.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.