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.