Send pre-approved WhatsApp template (HSM) messages to opted-in users outside the 24-hour session window via POST /template/msg, and list an app's templates and their approval status via GET /template/list/{appName}.
openapi: 3.0.3
info:
title: Gupshup WhatsApp Business API
description: >-
REST API for sending and managing WhatsApp Business messages through Gupshup.
Messages are sent from a registered WhatsApp Business number that is bound to a
Gupshup app; requests are authenticated with an `apikey` header tied to your
Gupshup account. This document models the WhatsApp messaging surface on
`https://api.gupshup.io/wa/api/v1` - sending session messages, sending
pre-approved template (HSM) messages, managing user opt-in / opt-out, listing
opted-in users, and listing an app's templates.
Scope and honesty note: the send-message (`POST /msg`) and send-template
(`POST /template/msg`) operations are confirmed against Gupshup's public API
reference. The opt-in / opt-out, users, and template-list operations are
documented in Gupshup's WhatsApp API guide (historically under the `/sm` path,
now migrating to the `/wa` path shown here); their request and response bodies
are MODELED from the documentation rather than copied from a machine-readable
source, and Gupshup uses `application/x-www-form-urlencoded` request bodies.
Verify exact field names and response shapes against the live documentation
before relying on this specification.
version: '1.0'
contact:
name: Gupshup
url: https://www.gupshup.io
x-modeled: true
servers:
- url: https://api.gupshup.io/wa/api/v1
description: Gupshup WhatsApp Business API
security:
- apiKeyAuth: []
tags:
- name: Messaging
description: Send WhatsApp session messages.
- name: Templates
description: Send and list WhatsApp template (HSM) messages.
- name: Opt-In
description: Manage user opt-in / opt-out and list interacted users.
paths:
/msg:
post:
operationId: sendMessage
tags:
- Messaging
summary: Send a WhatsApp session message
description: >-
Sends a WhatsApp message from a registered business number to a recipient.
The `message` field is a JSON-encoded object whose `type` selects the
message kind (text, image, file, audio, video, sticker, location, contact,
or interactive list / quick reply). Confirmed endpoint. Cannot be called
directly from a browser / client-side JS.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SendMessageRequest'
responses:
'202':
description: Message accepted for asynchronous delivery.
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'400':
$ref: '#/components/responses/BadRequest'
/template/msg:
post:
operationId: sendTemplateMessage
tags:
- Templates
summary: Send a WhatsApp template message
description: >-
Sends a pre-approved template (HSM) message to an opted-in user, used for
business-initiated notifications outside the 24-hour session window.
Confirmed endpoint.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SendTemplateRequest'
responses:
'202':
description: Template message accepted for asynchronous delivery.
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'400':
$ref: '#/components/responses/BadRequest'
/template/list/{appName}:
parameters:
- $ref: '#/components/parameters/AppName'
get:
operationId: listTemplates
tags:
- Templates
summary: List an app's templates
description: >-
Returns the message templates registered for an app along with their
approval status. Modeled from documentation.
responses:
'200':
description: A list of templates.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/app/opt/in/{appName}:
parameters:
- $ref: '#/components/parameters/AppName'
post:
operationId: markUserOptIn
tags:
- Opt-In
summary: Mark a user opt-in
description: >-
Records that a user has consented to receive messages from the business,
enabling template notifications to that number. Modeled from documentation.
Legacy opt-in APIs are not supported for apps created after Aug 2025.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/OptRequest'
responses:
'200':
description: Opt-in recorded.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/app/opt/out/{appName}:
parameters:
- $ref: '#/components/parameters/AppName'
post:
operationId: markUserOptOut
tags:
- Opt-In
summary: Mark a user opt-out
description: >-
Records that a user has opted out of receiving messages from the business.
Modeled from documentation.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/OptRequest'
responses:
'200':
description: Opt-out recorded.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/users/{appName}:
parameters:
- $ref: '#/components/parameters/AppName'
get:
operationId: listUsers
tags:
- Opt-In
summary: List interacted users and opt-in status
description: >-
Returns the users who have interacted with your business phone number and
their opt-in status. Modeled from documentation.
responses:
'200':
description: A list of users.
content:
application/json:
schema:
$ref: '#/components/schemas/UserListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: apikey
description: >-
Account API key sent in the `apikey` request header. Available from the
Gupshup dashboard. Scopes requests to your account and its registered apps.
parameters:
AppName:
name: appName
in: path
required: true
description: The Gupshup app name registered to the WhatsApp business number.
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid apikey.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: The request was malformed or missing required parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
status:
type: string
example: error
message:
type: string
StatusResponse:
type: object
properties:
status:
type: string
example: success
SendMessageResponse:
type: object
description: Asynchronous accept response carrying a Gupshup message identifier.
properties:
status:
type: string
example: submitted
messageId:
type: string
description: Gupshup unique message identifier used to correlate webhook delivery events.
SendMessageRequest:
type: object
required:
- channel
- source
- destination
- message
- src.name
properties:
channel:
type: string
description: Messaging channel.
example: whatsapp
source:
type: string
description: Registered WhatsApp Business phone number (with country code).
destination:
type: string
description: Recipient phone number (with country code).
message:
type: string
description: >-
JSON-encoded message object. Its `type` field selects the kind - text,
image, file, audio, video, sticker, location, contact, list, or
quick_reply - with type-specific fields alongside.
example: '{"type":"text","text":"Hello from Gupshup"}'
src.name:
type: string
description: Gupshup app name registered to the source number.
disablePreview:
type: boolean
description: Optional. Disables URL preview for text messages.
encode:
type: boolean
description: Optional. Controls encoding of text / interactive list messages.
SendTemplateRequest:
type: object
required:
- channel
- source
- destination
- template
- src.name
properties:
channel:
type: string
example: whatsapp
source:
type: string
description: Registered WhatsApp Business phone number.
destination:
type: string
description: Recipient phone number (must be opted-in).
template:
type: string
description: >-
JSON-encoded template object referencing an approved template id and its
parameter values, e.g. {"id":"<template-id>","params":["value1","value2"]}.
example: '{"id":"00000000-0000-0000-0000-000000000000","params":["Kin","ORD-42"]}'
message:
type: string
description: >-
Optional JSON-encoded media header object for media templates
(image / document / video).
src.name:
type: string
description: Gupshup app name registered to the source number.
OptRequest:
type: object
required:
- user
properties:
user:
type: string
description: The user's phone number (with country code) to opt in or out.
TemplateListResponse:
type: object
properties:
status:
type: string
example: success
templates:
type: array
items:
$ref: '#/components/schemas/Template'
Template:
type: object
properties:
id:
type: string
elementName:
type: string
category:
type: string
status:
type: string
description: Approval status (e.g. APPROVED, PENDING, REJECTED).
languageCode:
type: string
data:
type: string
description: Template body text with placeholders.
UserListResponse:
type: object
properties:
status:
type: string
example: success
users:
type: array
items:
$ref: '#/components/schemas/User'
User:
type: object
properties:
phoneCode:
type: string
phoneNumber:
type: string
optinStatus:
type: string
description: Whether the user is opted in.
lastInteraction:
type: string
description: Timestamp of the user's last interaction.