Conversation Search

Search conversations

get

Required Permission: chatbots.conversations.search

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Query parameters

querystringRequired

The search term.

viewIdstringRequired

The ID of the view within which the search is conducted.

Responses

200Success

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get/v1/chatbots/{chatbotId}/conversations/search

GET /v1/chatbots/{chatbotId}/conversations/search?query=text&viewId=text HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "results": {
    "facetCounts": [
      {
        "counts": [
          {
            "count": 42,
            "highlighted": "<em>whatsapp</em>",
            "value": "whatsapp"
          }
        ],
        "fieldName": "channelType",
        "stats": {
          "max": 100,
          "avg": 45.5,
          "min": 1,
          "sum": 1820
        }
      }
    ],
    "found": 150,
    "hits": [
      {
        "conversation": {
          "id": "conv_abc123xyz",
          "contactId": "contact_def456",
          "archived": false,
          "channelId": "channel_ghi789",
          "channelType": "whatsapp",
          "chatbotId": "bot_jkl012",
          "idToken": "token_mno345",
          "language": "DE",
          "operatorId": "op_pqr678",
          "photoUrl": "https://example.com/photos/user123.jpg",
          "sessionCount": 3,
          "tags": [
            "vip",
            "sales"
          ],
          "unread": true,
          "variables": {
            "customer_name": "John",
            "order_id": "12345"
          },
          "lastBlock": {
            "id": "blk_abc123",
            "name": "Welcome Message"
          },
          "lastButton": {
            "id": "blk_abc123",
            "name": "Welcome Message"
          },
          "created": "2025-10-05T10:00:00Z",
          "updated": "2025-10-05T12:30:00Z",
          "providerId": "wa_123456789",
          "name": "John Doe",
          "lastMessage": {
            "text": "text",
            "file": {
              "name": "text",
              "url": "text",
              "type": "text",
              "mimeType": "text",
              "size": 1,
              "attachmentRef": "text",
              "caption": "text",
              "transcript": "text"
            },
            "buttons": {
              "buttons": [
                {
                  "label": "text",
                  "type": "text",
                  "value": "text",
                  "payload": "text"
                }
              ]
            },
            "selectedButton": {
              "label": "text",
              "value": "text",
              "payload": "text",
              "type": "text",
              "reference": "text"
            },
            "template": {
              "body": "text",
              "header": "text",
              "footer": "text"
            },
            "contact": {
              "addresses": [
                {
                  "city": "text",
                  "country": "text",
                  "countryCode": "text",
                  "street": "text",
                  "type": "text",
                  "zip": "text"
                }
              ],
              "emails": [
                {
                  "email": "name@gmail.com",
                  "type": "text"
                }
              ],
              "name": {
                "firstName": "text",
                "formattedName": "text",
                "lastName": "text"
              },
              "org": {
                "company": "text",
                "title": "text"
              },
              "phones": [
                {
                  "phone": "text",
                  "type": "text",
                  "waId": "text"
                }
              ]
            },
            "location": {
              "latitude": 1,
              "longitude": 1
            },
            "note": {
              "text": "text",
              "mentions": [
                "text"
              ]
            },
            "voiceHangup": {
              "reason": "text",
              "headers": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              }
            },
            "voiceTransfer": {
              "target": "text",
              "reason": "text",
              "headers": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              }
            },
            "agentHandover": {
              "reason": "text",
              "timeoutSeconds": 1,
              "agentId": "text",
              "groupId": "text",
              "assignmentMethod": "text"
            },
            "email": {
              "subject": "text",
              "body": "text",
              "from": "text",
              "to": [
                "text"
              ],
              "cc": [
                "text"
              ],
              "bcc": [
                "text"
              ],
              "attachmentIds": [
                "text"
              ],
              "references": [
                "text"
              ],
              "attachments": [
                {
                  "id": "att_123",
                  "name": "invoice.pdf",
                  "created": "2024-01-01T00:00:00Z",
                  "updated": "2024-01-01T00:00:00Z",
                  "size": 102400,
                  "contentType": "application/pdf",
                  "selfLink": "bucketId-objectId/filename.filetype",
                  "metadata": {
                    "source": "email"
                  }
                }
              ]
            },
            "transcription": {
              "text": "text",
              "language": "text",
              "audioRef": "text"
            },
            "textToSpeech": {
              "text": "text",
              "speech": "text"
            },
            "reaction": {
              "reactionToMid": "text",
              "action": "text",
              "reaction": "text",
              "emoji": "text"
            },
            "callSettings": {
              "userInputSpeechDetectionTimeout": 1,
              "dtmf": true,
              "bargeIn": true
            },
            "metaWhatsappTemplate": {
              "templateName": "order_shipped_notification",
              "language": "DE",
              "bodyText": "Your order {{1}} has been shipped.",
              "headerText": "text",
              "footerText": "text",
              "header": {
                "file": {
                  "name": "header_image.png",
                  "url": "https://storage.example.com/files/header.png",
                  "type": "image",
                  "mimeType": "image/png",
                  "size": 51200,
                  "attachmentRef": "att_header123"
                },
                "parameters": [
                  "Order #12345"
                ]
              },
              "bodyParameters": [
                "#12345"
              ],
              "buttons": [
                {
                  "label": "Track Order",
                  "type": "URL",
                  "url": "https://example.com/track/{{1}}",
                  "value": "track_order"
                }
              ]
            },
            "operator": {
              "operatorId": "op_abc123xyz"
            },
            "delay": 1,
            "leadAiId": "text"
          },
          "snoozed": "2025-10-06T09:00:00Z",
          "lastUserAction": "2025-10-05T12:25:00Z",
          "mentions": [
            "user_123",
            "user_456"
          ],
          "mentionsRead": {
            "user_123": true,
            "user_456": false
          },
          "notes": {
            "notes": [
              "Customer prefers email contact",
              "VIP customer"
            ]
          },
          "lastSender": "user",
          "userInput": {
            "redirect": "flow_abc123",
            "isSensitive": false
          },
          "environment": "test",
          "metadata": {
            "source": "website",
            "campaign": "summer_sale"
          },
          "lastUserInput": "I need help with my order",
          "leadAiConversation": {
            "flowId": "flow_xyz789",
            "stepId": "step_abc123",
            "interactions": 5,
            "executionId": "exec_def456"
          },
          "team": {
            "teamId": "team_support_01"
          },
          "state": 0,
          "lastAssignedOperatorId": "op_xyz789",
          "lastSeen": "2025-10-05T12:30:00Z"
        },
        "highlights": [
          {
            "field": "content.text",
            "matchedTokens": [
              "text"
            ],
            "snippet": "text"
          }
        ],
        "textMatch": "order confirmation shipping"
      }
    ],
    "outOf": 10000,
    "page": 1,
    "searchTimeMs": 25
  },
  "error": "text"
}

Searches conversations for external inbox users

get

Required Permission: chatbots.conversations.search-external