{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","partial","tabs","tab"]},"type":"markdown"},"seo":{"title":"Conversations","description":"Complete developer documentation for the eCommunicate Omnichannel platform. WhatsApp Cloud, WhatsApp Lite, SMS, Live Chat, and Conversations APIs. Send messages, manage templates, configure webhooks, and build customer engagement at scale.","siteUrl":"https://docs.ecommunicate.co.za","keywords":["eCommunicate API","WhatsApp Business API","SMS API","omnichannel messaging","WhatsApp templates","messaging platform","South Africa messaging API"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"conversations","__idx":0},"children":["Conversations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Conversations API enables long-lived WhatsApp conversations that remain open until explicitly closed — they are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," subject to the standard 24-hour session window."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Not the same as WhatsApp sessions"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Standard WhatsApp messages have a 24-hour customer service window. The Conversations API creates persistent conversations that stay open for days, weeks, or months. Think automotive sales, ongoing support cases, or multi-day negotiations."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Authentication Required"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All API requests require your Developer Key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header. No ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer"]}," prefix — pass the key directly."," ","See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication"},"children":["Authentication"]}," for setup and security best practices."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"conversation-lifecycle","__idx":1},"children":["Conversation lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every conversation follows four stages:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"CREATE ──> SEND MESSAGES ──> CHECK TIME ──> CLOSE\n                  ↑              │\n                  └──────────────┘\n"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-create-a-conversation","__idx":2},"children":["1. Create a conversation"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /payless4messaging-service/WhatsApp/WhatsAppConversations/createWhatsAppConversation\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sender\": \"+27123456789\",\n  \"recipient\": \"+27987654321\",\n  \"customerUserId\": \"ZA.1021033720668862\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient"]}," is the customer's phone number. You may instead (or additionally) pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}," (the customer ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BSUID"]},", e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZA.1021033720668862"]},") — supply at least one. When both are present the phone takes precedence and the BSUID is stored as a durable fallback; pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}," on its own to open a conversation with a customer who has no phone number."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sender\": \"27123456789\",\n  \"recipient\": \"+27987654321\",\n  \"customerUserId\": \"ZA.1021033720668862\",\n  \"conversationId\": \"486268ed-f233-4c3b-8321-dc69c7ba984b\",\n  \"conversationState\": \"ACTIVE\",\n  \"clientRef\": \"MyClient\",\n  \"createdTime\": \"2026-07-16T10:30:00.000+00:00\",\n  \"conversationStatusCode\": \"200\",\n  \"conversationStatusMessage\": \"Conversation started.\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The conversation UUID — needed for every subsequent operation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationState"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]}," on a new conversation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationStatusCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"200\""]}," when a new conversation was created; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"452\""]}," when an active conversation already exists for this sender and recipient (the existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationId"]}," is returned)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The customer BSUID, if one was supplied (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," otherwise)"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Save the conversationId"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll need the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationId"]}," for all subsequent operations — sending messages, checking time, and closing the conversation. A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationStatusCode"]}," of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"452\""]}," means a conversation was already open — reuse the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationId"]}," rather than treating it as an error."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-send-messages","__idx":3},"children":["2. Send messages"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /whatsapp-api-service/v2/json\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messageType"]}," must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"CONVERSATION\""]},". Five message types are supported:"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Addressing a recipient — phone or BSUID"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every customer has a durable, business-scoped user id (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BSUID"]},", alpha usernames — e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZA.1021033720668862"]},") that stays stable for your business even if the customer changes their phone number. Address a recipient by phone (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]},"), by BSUID (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]},"), or both — supply at least one. When both are present, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]}," takes precedence and the BSUID rides along as a durable fallback. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The phone number remains the primary identifier today"]}," — store the BSUID now and rely on it as phone numbers become optional."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each entry in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipients"]}," (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientNumbers"]},") accepts:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recipient phone number in international format (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+27987654321"]},"). Required unless ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}," is supplied"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recipient ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BSUID"]}," (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZA.1021033720668862"]},"), durable across phone-number changes. Supply alongside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]}," (phone wins, BSUID kept as a fallback) or on its own to address a recipient with no phone. A malformed value is ignored, so a BSUID-only send then requires a valid ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]},". Required unless ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]}," is supplied"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ctId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client-defined tracking id, echoed back in delivery receipts and webhooks"]}]}]}]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Text Only","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sender\": \"+27123456789\",\n  \"template_name\": \"your_template\",\n  \"template_id\": \"template-uuid\",\n  \"messageType\": \"CONVERSATION\",\n  \"messages\": [\n    {\n      \"recipients\": [{ \"to\": \"+27987654321\", \"customerUserId\": \"ZA.1021033720668862\" }],\n      \"components\": [\n        { \"type\": \"body\", \"parameters\": [\"John\"] }\n      ]\n    }\n  ]\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Text + Media","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sender\": \"+27123456789\",\n  \"template_name\": \"your_template\",\n  \"template_id\": \"template-uuid\",\n  \"messageType\": \"CONVERSATION\",\n  \"messages\": [\n    {\n      \"recipients\": [{ \"to\": \"+27987654321\" }],\n      \"components\": [\n        { \"type\": \"body\", \"parameters\": [\"John\"] }\n      ],\n      \"media\": {\n        \"url\": \"https://example.com/brochure.pdf\",\n        \"caption\": \"Product Brochure\"\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Quick Reply","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Quick Reply buttons use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationState"]}," to control the conversation flow:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sender\": \"+27123456789\",\n  \"template_name\": \"your_template\",\n  \"template_id\": \"template-uuid\",\n  \"messageType\": \"CONVERSATION\",\n  \"messages\": [\n    {\n      \"recipients\": [{ \"to\": \"+27987654321\" }],\n      \"components\": [\n        { \"type\": \"body\", \"parameters\": [\"John\"] },\n        {\n          \"type\": \"button\",\n          \"parameters\": [\"Interested\", \"Not Now\"],\n          \"conversationParameters\": [\n            { \"payload\": \"Interested\", \"conversationState\": \"start\" },\n            { \"payload\": \"Not Now\", \"conversationState\": \"end\" }\n          ]\n        }\n      ]\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"State"},"children":["State"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Effect"},"children":["Effect"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationState: \"start\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keeps the conversation open for follow-up messages"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversationState: \"end\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Closes the conversation when the recipient taps this button"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Card","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rich card with media and body text:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sender\": \"+27123456789\",\n  \"template_name\": \"your_template\",\n  \"template_id\": \"template-uuid\",\n  \"messageType\": \"CONVERSATION\",\n  \"messages\": [\n    {\n      \"recipients\": [{ \"to\": \"+27987654321\" }],\n      \"components\": [\n        { \"type\": \"body\", \"parameters\": [\"2024 Model X\", \"From $35,000\"] }\n      ],\n      \"media\": {\n        \"url\": \"https://example.com/car.jpg\",\n        \"caption\": \"2024 Model X\"\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Call to Action","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Template with actionable button URLs:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sender\": \"+27123456789\",\n  \"template_name\": \"your_template\",\n  \"template_id\": \"template-uuid\",\n  \"messageType\": \"CONVERSATION\",\n  \"messages\": [\n    {\n      \"recipients\": [{ \"to\": \"+27987654321\" }],\n      \"components\": [\n        { \"type\": \"body\", \"parameters\": [\"John\"] },\n        {\n          \"type\": \"button\",\n          \"parameters\": [\"https://example.com/schedule\"]\n        }\n      ]\n    }\n  ]\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-check-remaining-time","__idx":4},"children":["3. Check remaining time"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /payless4messaging-service/WhatsApp/WhatsAppConversations/getRemainingTime?conversationId=conv-uuid\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns the remaining time in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["seconds"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["83053"]}," = approximately 23 hours)."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Time management"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Monitor remaining time and send follow-up messages or close the conversation before it expires. Expired conversations cannot accept new messages."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-close-the-conversation","__idx":5},"children":["4. Close the conversation"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /payless4messaging-service/WhatsApp/WhatsAppConversations/closeWhatsAppConversation?conversationId=conv-uuid\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"closeStatus\": true,\n  \"closeMessage\": \"CONVERSATION CLOSED SUCCESSFULLY\",\n  \"tqrmtId\": \"tracking-uuid\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"managing-conversations","__idx":6},"children":["Managing conversations"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-your-conversations","__idx":7},"children":["List your conversations"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /payless4messaging-service/WhatsApp/WhatsAppConversations/getAllWhatsAppConversationsForCurrentUser?page=0&size=20\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-conversations-by-client","__idx":8},"children":["List conversations by client"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /payless4messaging-service/WhatsApp/WhatsAppConversations/getAllWhatsAppConversationsByClientRef?clientRef=MyClient\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"conversation-analytics","__idx":9},"children":["Conversation analytics"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /payless4messaging-service/WhatsApp/WhatsAppAnalytics/getConversationAnalyticsForCurrentLoginUser\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Query parameters:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required."]}," Start of the reporting period in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD HH:mm:ss"]}," format (UTC)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required."]}," End of the reporting period in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD HH:mm:ss"]}," format (UTC)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messageType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["enum"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOTIFICATION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SESSION24HOUR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONVERSATION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHAT"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"conversationSubmitted\": 150,\n  \"conversationSent\": 148,\n  \"conversationDelivered\": 145,\n  \"conversationRead\": 120,\n  \"conversationFailed\": 2\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"conversation-states","__idx":10},"children":["Conversation states"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"State"},"children":["State"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conversation is active and accepting messages"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLOSED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conversation has been closed (by API call, button click, or expiration)"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retrieving-conversation-messages","__idx":11},"children":["Retrieving conversation messages"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To retrieve the messages exchanged within a live chat conversation (e.g. for a chatbot or agent dashboard), see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/live-chat#chatbot-conversation-flow"},"children":["Chatbot conversation flow"]}," guide. It walks through receiving an incoming webhook, looking up the chat participant, and fetching the full message history."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-cases","__idx":12},"children":["Use cases"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Why conversations?"},"children":["Why conversations?"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automotive sales"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Multi-day negotiation with test drive scheduling"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Insurance claims"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Back-and-forth document exchange over weeks"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Real estate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Property viewing coordination spanning days"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Customer onboarding"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Step-by-step guided onboarding over multiple sessions"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Travel bookings"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Itinerary planning with multiple touchpoints"]}]}]}]}]}]},"headings":[{"value":"Conversations","id":"conversations","depth":1},{"value":"Conversation lifecycle","id":"conversation-lifecycle","depth":2},{"value":"1. Create a conversation","id":"1-create-a-conversation","depth":3},{"value":"2. Send messages","id":"2-send-messages","depth":3},{"value":"3. Check remaining time","id":"3-check-remaining-time","depth":3},{"value":"4. Close the conversation","id":"4-close-the-conversation","depth":3},{"value":"Managing conversations","id":"managing-conversations","depth":2},{"value":"List your conversations","id":"list-your-conversations","depth":3},{"value":"List conversations by client","id":"list-conversations-by-client","depth":3},{"value":"Conversation analytics","id":"conversation-analytics","depth":3},{"value":"Conversation states","id":"conversation-states","depth":2},{"value":"Retrieving conversation messages","id":"retrieving-conversation-messages","depth":2},{"value":"Use cases","id":"use-cases","depth":2}],"frontmatter":{"title":"Conversations","description":"Long-lived WhatsApp conversations that stay open until explicitly closed — beyond the 24-hour window.","seo":{"title":"Conversations"}},"lastModified":"2026-07-16T12:13:05.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/conversations","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}