Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Insider Conversational API
version: 1.0.0
contact:
name: Insider One Support
email: support@useinsider.com
url: https://academy.insiderone.com/docs/insider-one-apis-1
termsOfService: https://insiderone.com/terms-of-use/
description: 'Operations tagged Conversational API across 2 of this provider''s published API definitions: insider-gateway-openapi.yml, insider-whatsapp-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://gw.useinsider.com
- url: https://whatsapp.useinsider.com
tags:
- name: Conversational API
paths:
/api/wa/v2/conversational/messages/send:
post:
operationId: sendConversationalWhatsappMessagesWithOauth20
summary: Send Conversational WhatsApp Messages with OAuth 2.0
tags:
- Conversational API
description: "WhatsApp Transactional API v2 is a REST API that enables your systems to send conversational messages through the WhatsApp Business Platform.\n\nTo send conversational WhatsApp messages using OAuth 2.0, you must first generate an OAuth 2.0 credential. For step-by-step instructions, refer to OAuth 2.0 Credentials.\n\nBefore sending Conversational WhatsApp template messages, make sure you create your template in InOne first. Refer to Create a WhatsApp Business Standard Template on InOne for step-by-step guidance.\n\nRefer to the visual below for an example of how a conversational WhatsApp template message is displayed. \n\nSample Request\nUse the request below to send conversational messages via WhatsApp. In addition to templates, message types such as text and media can be sent.\n\n{\n \"from\": \"+111111111\",\n \"messages\": [\n {\n \"phone_number\": \"+1234567890\",\n \"user_id\": \"user-uuid-123\",\n \"message\": {\n \"type\": \"text\",\n \"text\": {\n \"body\": \"Hello! How can I help you?\",\n \"preview_url\": false\n }\n }\n }\n ]\n}\n\nBody Parameters\nThis endpoint shares the same parameters as the Transactional WhatsApp Messages with OAuth 2.0. The primary distinction is that conversational message types, such as text, image, video, document, audio, location, and interactive, are available for the message.type field.\n\nSample Responses\n200 OK\nThis code indicates that the request has been completed.\n\n{\n \"keys\": [\n \"whatsapp-660e8400-e29b-41d4-a716-446655440001\"]\n}\n\nError Codes\nThese endpoints return the same error codes as the Transactional WhatsApp Messages with OAuth 2.0 (2001, 2002, 2003).\n\nCode\nHTTP Status\nDescription\n\n2001\n400\nThe request body could not be decoded.\n\n2002\n400\nThe request body failed validation.\n\n2003\n400\nThe message could not be sent due to a provider error or an internal system issue.\n\nMedia Operation Errors\n\nCode\nHTTP Status\nDescription\n\n2017\n400\nProvider not found or upload error\n\n2018\n400\nError retrieving media information\n\n2019\n400\nMedia download error\n\nINVALID_FILE\n400\nInvalid file or file could not be read\n\nSystem Errors\n\nHTTP Status\nDescription\n\n503 Service Unavailable\nThe system is currently in maintenance mode"
requestBody:
content:
application/json:
example:
from: '+111111111'
messages:
- phone_number: '+1234567890'
user_id: user-uuid-123
message:
type: text
text:
body: Hello! How can I help you?
preview_url: false
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- OAuth2: []
servers:
- url: https://gw.useinsider.com
/api/wa/v2/conversational/settings:
post:
operationId: updateConversationalWhatsappWebhookSettingsWithOauth20
summary: Update Conversational WhatsApp Webhook Settings with OAuth 2.0
tags:
- Conversational API
description: "This endpoint helps you update the webhook URL and other relevant settings for conversational messages.\n\nThe system supports two grant types for OAuth2 authentication:\n\ngrant_type: client_credentials\n\ngrant_type: refresh_token\n\nClient Credentials Request\ncurl -X POST \"https://gw.useinsider.com/api/wa/v2/conversational/settings\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer your_access_token\" \\\n -d '{\n \"webhook_url\": \"https://partner.example.com/webhooks/conversational\",\n \"from\": \"+1234567890\",\n \"auth_type\": \"oauth2\",\n \"oauth2\": {\n \"grant_type\": \"client_credentials\",\n \"token_url\": \"https://oauth.partner.com/oauth/token\",\n \"client_id\": \"your_client_id\",\n \"client_secret\": \"your_client_secret\",\n \"scopes\": [\n \"webhook.write\"\n ],\n \"expires_in\": 3600\n }\n }'\n\nRefresh Token Request\ncurl -X POST \"https://gw.useinsider.com/api/wa/v2/conversational/settings\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer your_access_token\" \\\n -d '{\n \"webhook_url\": \"https://partner.example.com/webhooks/conversational\",\n \"from\": \"+1234567890\",\n \"auth_type\": \"oauth2\",\n \"oauth2\": {\n \"grant_type\": \"refresh_token\",\n \"token_url\": \"https://oauth.partner.com/oauth/token\",\n \"client_id\": \"your_client_id\",\n \"client_secret\": \"your_client_secret\",\n \"refresh_token\": \"your_refresh_token\",\n \"scopes\": [\n \"webhook.write\"\n ],\n \"expires_in\": 3600\n }\n }'\n\nError Codes\n\nCode\nHTTP Status\nDescription\n\n2010\n400\nThe settings request body could not be decoded.\n\n2011\n400\nThe settings request body failed validation.\n\n2012\n400\nAn error occurred while saving the settings.\n\n2020\n400\nThe webhook URL failed validation."
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- OAuth2: []
servers:
- url: https://gw.useinsider.com
/v1/conversational/send:
post:
operationId: sendConversationalWhatsappMessageTemplate
summary: Send Conversational WhatsApp Message Template
tags:
- Conversational API
description: "The WhatsApp Marketing product provides conversational messages, allowing users to initiate conversations with businesses after the business has sent an initial message. To create a conversational flow, one of the ways is to integrate a bot to reply to users' WhatsApp messages.\n\nThe Conversational API is designed for WhatsApp Bot connection.\n\nBody Parameters\n\nColumn\nDescription\nData Type\nRequired\n\nmessages\nAll messages are contained in the messages key. You can send multiple messages with a single request.\nArray\nYes\n\nfrom\nUse only if you are using multiple phone numbers. If you have only one phone number, you do not need to add this.\nString\nNo\n\nphoneNumber\nPhone number for the person you want to send a message to.\nString\nYes\n\nmessage\nMessage object\nObject\nYes\n\ntype\nMust be a “template” for this message type.\nString\nYes\n\nname\nTemplate name to be sent\nString\nYes\n\nlanguage\n\nObject\nYes\n\ncode\nTemplate language\nString\nYes\n\npolicy\nIt must be deterministic.\nString\nYes\n\nmessage variable components\n\nArray\nYes\n\ntype\nbody\nString\nYes\n\nbody parameters\n\nArray\nYes\n\ntype\ntext\nString\nYes\n\ntext\nParameter value\nString\nYes\n\nbutton components\n\nArray\nYes\n\ntype\nbutton\nString\nYes\n\nsub_type\nQuick_reply, URL, PHONE_NUMBER\nString\nYes\n\nindex\n\nString\nYes\n\nparameters\n\nArray\nYes\n\ntype\npayload\nString\nYes\n\npayload\nPayload value\nString\nYes\n\nSample Body\nYou can use the below sample request if you want to use the quick reply buttons:\n\ncurl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \\\n--header 'Content-Type: application/json' \\\n--header 'x-ins-auth-key: INS.**************************************' \\\n--data '{\n \"from\": \"{{PHONE_NUMBER}}\", //Example: +112312312\n \"messages\": [\n {\n \"phoneNumber\": \"+1**********\",\n \"message\": {\n \"type\": \"template\",\n \"template\": {\n \"name\": \"{{TEMPLATE_NAME}}\",\n \"language\": {\n \"code\": \"{{TEMPLATE_LANGUAGE_CODE}}\",\n \"policy\": \"deterministic\",\n },\n \"components\": [\n {\n \"type\": \"body\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"{{PARAMETER_VALUE}}\"\n }\n ]\n },\n {\n \"type\": \"button\",\n \"sub_type\": \"quick_reply\",\n \"index\": \"0\",\n \"parameters\": [\n {\n \"type\": \"payload\",\n \"payload\": \"1\"\n }\n ]\n },\n {\n \"type\": \"button\",\n \"sub_type\": \"quick_reply\",\n \"index\": \"1\",\n \"parameters\": [\n {\n \"type\": \"payload\",\n \"payload\": \"2\"\n }\n ]\n }\n ]\n }\n }\n }\n ]\n}'\n\nIf you want to use CTA (Call To Action), you can use the below sample request:\n\ncurl --location 'https://whatsapp.useinsider.com/v1/send' \\\n--header 'x-ins-auth-key: INS.kjQu-+bL4HpeZqvgr1j0.d4IVgHl9GcE+_eaKxNA3P8M3q8-emrO3-zalg9GSF29mK+Jz5k' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"messages\": [\n {\n \"phoneNumber\": \"+994558964184\",\n \"message\": {\n \"type\": \"template\",\n \"template\": {\n \"name\": \"mert_masterfile_media_with_button\",\n \"language\": {\n \"code\": \"en\",\n \"policy\": \"deterministic\"\n },\n \"components\": [\n {\n \"type\": \"header\",\n \"sub_type\": \"\",\n \"index\": \"\",\n \"parameters\": [\n {\n \"type\": \"image\",\n \"image\": {\n \"link\": \"https://inshoppingcart.com/seleniumautomation/wp-content/uploads/2018/08/cap-2.jpg\"\n }\n }\n ]\n },\n {\n \"type\": \"body\",\n \"sub_type\": \"\",\n \"index\": \"\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"https://vikingsankara.com?abc=sha\"\n }\n ]\n },\n {\n \"type\": \"button\",\n \"sub_type\": \"url\",\n \"index\": \"0\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"https://vikingsankara.com\"\n }\n ]\n }\n ]\n }\n }\n }\n ]\n}'\n\nIf you don't want to use CTA, you can use the below sample request:\n\ncurl --location 'https://whatsapp.useinsider.com/v1/send' \\\n--header 'Content-Type: application/json' \\\n--header 'x-ins-auth-key: INS.tiNlcL284J8dwCpfoqdR.gpyLwFG-0fSHPS9+kZYNsI-D2IWFNjlaRDlXJrZjx2_ZPTP37I' \\\n--data '{\n \"messages\": [\n {\n \"phoneNumber\": \"+994558964184\",\n \"message\": {\n \"type\": \"template\",\n \"template\": {\n \"name\": \"7_image_header_no_button_copy\",\n \"language\": {\n \"code\": \"fi\",\n \"policy\": \"deterministic\"\n },\n \"components\": [\n {\n \"type\": \"header\",\n \"sub_type\": \"\",\n \"index\": \"\",\n \"parameters\": [\n {\n \"type\": \"image\",\n \"image\": {\n \"link\": \"https://image.useinsider.com/vikingsankara/media/whatsapp-business/11521/83rbBaWO7H63VmACSXiZ1716506118.jpg\"\n }\n }\n ]\n },\n {\n \"type\": \"body\",\n \"sub_type\": \"\",\n \"index\": \"\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"shahla\"\n }\n ]\n }\n ]\n }\n }\n }\n ]\n}'\n\nSample Responses\nOne key information will be returned for each message to be sent. This key will be added to all events related to the message.\n\n{\n \"keys\": [\n \"whatsapp-*************************\"\n ]\n}\n\nLimitations\n\nAll functions must be executed with a simple HTTPS POST request.\n\nOnly new WhatsApp messages can be sent via this API. No data can be retrieved.\n\nThe API Key should be provided as the authorization key on the request header. If the key is incorrect, the operation will not be executed and an authorization error will return in the response.\n\nThe rate limit is 10 requests per second."
security:
- InsAuthKey: []
requestBody:
content:
application/json:
examples:
default:
value:
messages:
- phoneNumber: +1**********
message:
type: template
template:
name: '{{TEMPLATE_NAME}}'
language:
code: '{{TEMPLATE_LANGUAGE_CODE}}'
components:
- type: body
parameters:
- type: text
text: '{{PARAMETER_VALUE}}'
- type: button
sub_type: quick_reply
index: '0'
parameters:
- type: payload
payload: '1'
- type: button
sub_type: quick_reply
index: '1'
parameters:
- type: payload
payload: '2'
send-conversational-whatsapp-carousel-template-message:
summary: Send Conversational WhatsApp Carousel Template Message
value:
from: '{{FROM}}'
messages:
- phoneNumber: '{{TO}}'
message:
type: template
template:
name: '{{TEMPLATE_NAME}}'
language:
code: '{{LANG_CODE}}'
policy: deterministic
components:
- type: body
parameters:
- type: text
text: '{{BODY_1}}'
- type: carousel
cards:
- card_index: 0
components:
- type: header
parameters:
- type: image
image:
id: '{{IMG_ID_1}}'
- type: body
parameters:
- type: text
text: '{{CARD_TEXT_1}}'
- type: button
sub_type: quick_reply
index: '0'
parameters:
- type: payload
payload: '{{PAYLOAD_1}}'
- type: button
sub_type: url
index: '1'
parameters:
- type: text
text: '{{URL_1}}'
- card_index: 1
components:
- type: header
parameters:
- type: image
image:
id: '{{IMG_ID_2}}'
- type: body
parameters:
- type: text
text: '{{CARD_TEXT_2}}'
- type: button
sub_type: quick_reply
index: '0'
parameters:
- type: payload
payload: '{{PAYLOAD_2}}'
- type: button
sub_type: url
index: '1'
parameters:
- type: text
text: '{{URL_2}}'
send-conversational-whatsapp-text-message:
summary: Send Conversational WhatsApp Text Message
value:
messages:
- phoneNumber: +1**********
message:
type: text
text:
preview_url: true
body: Example Message
send-conversational-whatsapp-media-message-image:
summary: Send Conversational WhatsApp Media Message (Image)
value:
messages:
- phoneNumber: +1**********
message:
type: image
image:
link: '{{IMAGE_URL}}'
caption: Media Message (Image)
send-conversational-whatsapp-media-message-document:
summary: Send Conversational WhatsApp Media Message (Document)
value:
messages:
- phoneNumber: +1**********
message:
type: document
audio:
link: '{{DOCUMENT_LINK}}'
caption: '{{DOCUMENT_DESCRIPTION}}'
filename: '{{DOCUMENT_NAME}}'
send-conversational-whatsapp-media-message-location:
summary: Send Conversational WhatsApp Media Message (Location)
value:
messages:
- phoneNumber: +1**********
message:
type: location
location:
longitude: '11.1111111'
latitude: '11.1111111'
name: '{{ADDRESS_NAME}}'
address: '{{FULL_ADDRESS}}'
send-conversational-whatsapp-message-with-button-reply:
summary: Send Conversational WhatsApp Message with Button Reply
value:
messages:
- phoneNumber: +1**********
message:
type: interactive
interactive:
type: button
header:
type: text
text: HEADER_TEXT
body:
text: BUTTON_TEXT
action:
buttons:
- type: reply
reply:
id: UNIQUE_BUTTON_ID_1
title: BUTTON_TITLE_1
- type: reply
reply:
id: UNIQUE_BUTTON_ID_2
title: BUTTON_TITLE_2
text/plain:
example: "{\n \"messages\": [\n {\n \"phoneNumber\": \"{{PHONE_NUMBER}}\",\n \"message\": {\n \"type\": \"template\",\n \"template\": {\n \"name\": \"{{OTP_TEMPLATE_NAME}}\",\n \"language\": {\n \"code\": \"en\",\n \"policy\": \"deterministic\",\n },\n \"components\": [\n {\n \"type\": \"body\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"{{OTP_CODE}}\"\n }\n ]\n },\n {\n \"type\": \"button\",\n \"sub_type\": \"url\",\n \"index\": \"0\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"{{OTP_CODE}}\"\n }\n ]\n }\n ]\n }\n }\n }\n ]\n}"
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
servers:
- url: https://whatsapp.useinsider.com
components:
responses:
TooManyRequests:
description: Too Many Requests. The published per-endpoint rate limit was exceeded; back off and retry, honouring Retry-After when present.
content:
application/json:
example:
message: Too Many Requests
status: 429
securitySchemes:
OAuth2:
type: oauth2
description: OAuth 2.0. Client ID / Client Secret are generated in the InOne panel under Settings > InOne Settings > Integration Settings > OAuth 2.0 Credentials, with per-channel scopes selected at generation time. Endpoint metadata read live from https://gw.useinsider.com/.well-known/oauth-authorization-server (RFC 8414).
flows:
clientCredentials:
tokenUrl: https://gw.useinsider.com/oauth2/token
scopes: {}
authorizationCode:
authorizationUrl: https://gw.useinsider.com/oauth2/authorize
tokenUrl: https://gw.useinsider.com/oauth2/token
refreshUrl: https://gw.useinsider.com/oauth2/token
scopes: {}
x-pkce:
- S256
x-revocation-endpoint: https://gw.useinsider.com/oauth2/revoke
x-discovery: well-known/insider-gw-oauth-authorization-server.json
InsAuthKey:
type: apiKey
in: header
name: X-INS-AUTH-KEY
description: Insider One authorization key for this API, generated in the InOne panel.
externalDocs:
description: Insider One API reference
url: https://academy.insiderone.com/docs/api-reference-welcome
x-refined-from:
- insider-gateway-openapi.yml
- insider-whatsapp-openapi.yml
x-provenance:
generated: '2026-08-13'
method: derived
source: postman/insider-one-apis.postman_collection.json
source_url: https://documenter.gw.postman.com/api/collections/24851117/2sB3dSR9bM
publisher_page: https://developers.insiderone.com/
note: Insider One publishes a single public Postman collection covering every REST API. This document is the subset of that collection served from analytics.api.useinsider.com.