# Search Conversations GET https://services.leadconnectorhq.com/conversations/search Returns a list of all conversations matching the search criteria along with the sort and filter options selected. ## Authentication Send `Authorization: Bearer ` using: - **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `conversations.readonly` ## Parameters ### Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Version` | string | Yes | API Version | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `locationId` | string | Yes | Location Id | | `contactId` | string | No | Contact Id | | `assignedTo` | string | No | User IDs that conversations are assigned to. Multiple IDs can be provided as comma-separated values. Use "unassigned" to fetch conversations not assigned to any user. | | `followers` | string | No | User IDs of followers to filter conversations by. Multiple IDs can be provided as comma-separated values. | | `mentions` | string | No | User Id of the mention. Multiple values are comma separated. | | `query` | string | No | Search paramater as a string | | `sort` | string | No | Sort paramater - asc or desc | | `startAfterDate` | any | No | Search to begin after the specified date - should contain the sort value of the last document | | `id` | string | No | Id of the conversation | | `limit` | number | No | Limit of conversations - Default is 20 | | `lastMessageType` | string | No | Type of the last message in the conversation as a string | | `lastMessageAction` | string | No | Action of the last outbound message in the conversation as string. | | `lastMessageDirection` | string | No | Direction of the last message in the conversation as string. | | `status` | string | No | The status of the conversation to be filtered - all, read, unread, starred | | `sortBy` | string | No | The sorting of the conversation to be filtered as - manual messages or all messages | | `sortScoreProfile` | string | No | Id of score profile on which sortBy.ScoreProfile should sort on | | `scoreProfile` | string | No | Id of score profile on which conversations should get filtered out, works with scoreProfileMin & scoreProfileMax | | `scoreProfileMin` | number | No | Minimum value for score | | `scoreProfileMax` | number | No | Maximum value for score | ## OpenAPI Specification ```json { "openapi": "3.0.0", "info": { "title": "LeadConnector API", "version": "v3" }, "servers": [ { "url": "https://services.leadconnectorhq.com" } ], "paths": { "/conversations/search": { "get": { "summary": "Search Conversations", "operationId": "searchConversations", "description": "Returns a list of all conversations matching the search criteria along with the sort and filter options selected.", "parameters": [ { "name": "Version", "in": "header", "description": "API Version", "required": true, "schema": { "type": "string", "enum": [ "v3" ] } }, { "name": "locationId", "required": true, "in": "query", "description": "Location Id", "schema": { "example": "ABCHkzuJQ8ZMd4Te84GK", "type": "string" } }, { "name": "contactId", "required": false, "in": "query", "description": "Contact Id", "schema": { "example": "9VEmS0si86GW6gXWU89b", "type": "string" } }, { "name": "assignedTo", "required": false, "in": "query", "description": "User IDs that conversations are assigned to. Multiple IDs can be provided as comma-separated values. Use \"unassigned\" to fetch conversations not assigned to any user.", "schema": { "example": "ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik", "type": "string" } }, { "name": "followers", "required": false, "in": "query", "description": "User IDs of followers to filter conversations by. Multiple IDs can be provided as comma-separated values.", "schema": { "example": "ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik", "type": "string" } }, { "name": "mentions", "required": false, "in": "query", "description": "User Id of the mention. Multiple values are comma separated.", "schema": { "example": "ABCHkzuJQ8ZMd4Te84GK,fGiae4CHkzoskh8thsik", "type": "string" } }, { "name": "query", "required": false, "in": "query", "description": "Search paramater as a string", "schema": { "example": "Search string", "type": "string" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort paramater - asc or desc", "schema": { "example": "asc", "enum": [ "asc", "desc" ], "type": "string" } }, { "name": "startAfterDate", "required": false, "in": "query", "description": "Search to begin after the specified date - should contain the sort value of the last document", "anyOf": [ { "type": "object", "properties": { "startAfterDate": { "type": "number", "description": "Search to begin after the specified date - should contain the sort value of the last document", "example": 1600854 } }, "title": "StartAfterNumberSchema" }, { "type": "object", "properties": { "startAfterDate": { "description": "Search to begin after the specified date - should contain the sort value of the last document", "example": [ 1600854, 1600851 ], "type": "array", "items": { "type": "string" } } }, "title": "StartAfterArrayNumberSchema" } ], "schema": { "example": 1600854, "type": "any" } }, { "name": "id", "required": false, "in": "query", "description": "Id of the conversation", "schema": { "example": "ABCHkzuJQ8ZMd4Te84GK", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Limit of conversations - Default is 20", "schema": { "example": 20, "type": "number" } }, { "name": "lastMessageType", "required": false, "in": "query", "description": "Type of the last message in the conversation as a string", "schema": { "example": "TYPE_SMS", "enum": [ "TYPE_CALL", "TYPE_SMS", "TYPE_EMAIL", "TYPE_SMS_REVIEW_REQUEST", "TYPE_WEBCHAT", "TYPE_SMS_NO_SHOW_REQUEST", "TYPE_CAMPAIGN_SMS", "TYPE_CAMPAIGN_CALL", "TYPE_CAMPAIGN_EMAIL", "TYPE_CAMPAIGN_VOICEMAIL", "TYPE_FACEBOOK", "TYPE_CAMPAIGN_FACEBOOK", "TYPE_CAMPAIGN_MANUAL_CALL", "TYPE_CAMPAIGN_MANUAL_SMS", "TYPE_GMB", "TYPE_CAMPAIGN_GMB", "TYPE_REVIEW", "TYPE_INSTAGRAM", "TYPE_WHATSAPP", "TYPE_CUSTOM_SMS", "TYPE_CUSTOM_EMAIL", "TYPE_CUSTOM_PROVIDER_SMS", "TYPE_CUSTOM_PROVIDER_EMAIL", "TYPE_IVR_CALL", "TYPE_ACTIVITY_CONTACT", "TYPE_ACTIVITY_INVOICE", "TYPE_ACTIVITY_PAYMENT", "TYPE_ACTIVITY_OPPORTUNITY", "TYPE_LIVE_CHAT", "TYPE_LIVE_CHAT_INFO_MESSAGE", "TYPE_ACTIVITY_APPOINTMENT", "TYPE_FACEBOOK_COMMENT", "TYPE_INSTAGRAM_COMMENT", "TYPE_CUSTOM_CALL", "TYPE_INTERNAL_COMMENT", "TYPE_ACTIVITY_EMPLOYEE_ACTION_LOG" ], "type": "string" } }, { "name": "lastMessageAction", "required": false, "in": "query", "description": "Action of the last outbound message in the conversation as string.", "schema": { "example": "manual", "enum": [ "automated", "manual" ], "type": "string" } }, { "name": "lastMessageDirection", "required": false, "in": "query", "description": "Direction of the last message in the conversation as string.", "schema": { "example": "inbound", "enum": [ "inbound", "outbound" ], "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "The status of the conversation to be filtered - all, read, unread, starred ", "schema": { "example": "all", "enum": [ "all", "read", "unread", "starred", "recents" ], "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "The sorting of the conversation to be filtered as - manual messages or all messages", "schema": { "example": "last_message_date", "enum": [ "last_manual_message_date", "last_message_date", "score_profile" ], "type": "string" } }, { "name": "sortScoreProfile", "required": false, "in": "query", "description": "Id of score profile on which sortBy.ScoreProfile should sort on", "schema": { "example": "ABCHkzuJQ8ZMd4Te84GK", "type": "string" } }, { "name": "scoreProfile", "required": false, "in": "query", "description": "Id of score profile on which conversations should get filtered out, works with scoreProfileMin & scoreProfileMax", "schema": { "example": "ABCHkzuJQ8ZMd4Te84GK", "type": "string" } }, { "name": "scoreProfileMin", "required": false, "in": "query", "description": "Minimum value for score", "schema": { "example": "ABCHkzuJQ8ZMd4Te84GK", "type": "number" } }, { "name": "scoreProfileMax", "required": false, "in": "query", "description": "Maximum value for score", "schema": { "example": "ABCHkzuJQ8ZMd4Te84GK", "type": "number" } } ], "responses": { "200": { "description": "Successfully fetched the conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendConversationResponseDto" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestDTO" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedDTO" } } } } }, "security": [ { "bearer": [ "conversations.readonly" ] } ] } } }, "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account.", "type": "http" }, "Agency-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.", "type": "http" } }, "schemas": { "SendConversationResponseDto": { "type": "object", "properties": { "conversations": { "description": "The list of all conversations found for the given query", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation Id", "example": "ABCHkzuJQ8ZMd4Te84GK" }, "contactId": { "type": "string", "description": "Contact Id", "example": "ABCHkzuJQ8ZMd4Te84GK" }, "locationId": { "type": "string", "description": "Location Id", "example": "ABCHkzuJQ8ZMd4Te84GK" }, "lastMessageBody": { "type": "string", "description": "Content of the most recent message in the conversation", "example": "This is a sample message body" }, "lastMessageType": { "type": "string", "description": "Channel/type of the most recent message (SMS, Email, Call, etc)", "example": "TYPE_SMS", "enum": [ "TYPE_CALL", "TYPE_SMS", "TYPE_EMAIL", "TYPE_SMS_REVIEW_REQUEST", "TYPE_WEBCHAT", "TYPE_SMS_NO_SHOW_REQUEST", "TYPE_CAMPAIGN_SMS", "TYPE_CAMPAIGN_CALL", "TYPE_CAMPAIGN_EMAIL", "TYPE_CAMPAIGN_VOICEMAIL", "TYPE_FACEBOOK", "TYPE_CAMPAIGN_FACEBOOK", "TYPE_CAMPAIGN_MANUAL_CALL", "TYPE_CAMPAIGN_MANUAL_SMS", "TYPE_GMB", "TYPE_CAMPAIGN_GMB", "TYPE_REVIEW", "TYPE_INSTAGRAM", "TYPE_WHATSAPP", "TYPE_CUSTOM_SMS", "TYPE_CUSTOM_EMAIL", "TYPE_CUSTOM_PROVIDER_SMS", "TYPE_CUSTOM_PROVIDER_EMAIL", "TYPE_IVR_CALL", "TYPE_ACTIVITY_CONTACT", "TYPE_ACTIVITY_INVOICE", "TYPE_ACTIVITY_PAYMENT", "TYPE_ACTIVITY_OPPORTUNITY", "TYPE_LIVE_CHAT", "TYPE_LIVE_CHAT_INFO_MESSAGE", "TYPE_ACTIVITY_APPOINTMENT", "TYPE_FACEBOOK_COMMENT", "TYPE_INSTAGRAM_COMMENT", "TYPE_CUSTOM_CALL", "TYPE_INTERNAL_COMMENT", "TYPE_ACTIVITY_EMPLOYEE_ACTION_LOG" ] }, "type": { "type": "string", "description": "Primary channel/type of the conversation (Phone, Email, etc)", "example": "TYPE_PHONE", "enum": [ "TYPE_PHONE", "TYPE_EMAIL", "TYPE_FB_MESSENGER", "TYPE_REVIEW", "TYPE_GROUP_SMS" ] }, "unreadCount": { "type": "number", "description": "Number of unread messages in this conversation", "example": 1 }, "fullName": { "type": "string", "description": "Complete name of the contact (first and last name)", "example": "John Doe" }, "contactName": { "type": "string", "description": "Alternative display name for the contact - used when full name is not available", "example": "John Doe Company" }, "email": { "type": "string", "description": "Primary email address of the contact", "example": "johndoe@mailingdomain.com" }, "phone": { "type": "string", "description": "Primary phone number of the contact", "example": "+15550001234" } }, "required": [ "id", "contactId", "locationId", "lastMessageBody", "lastMessageType", "type", "unreadCount", "fullName", "contactName", "email", "phone" ], "title": "ConversationSchema" } }, "total": { "type": "number", "description": "Total Number of results found for the given query", "example": 100 } }, "required": [ "conversations", "total" ], "title": "SendConversationResponseDto" }, "BadRequestDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Bad Request" } }, "title": "BadRequestDTO" }, "UnauthorizedDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid token: access token is invalid" }, "error": { "type": "string", "example": "Unauthorized" } }, "title": "UnauthorizedDTO" } } } } ``` ## Code Examples **cURL** ```bash curl -L -X GET 'https://services.leadconnectorhq.com/conversations/search?locationId=' \ -H 'Authorization: Bearer ' \ -H 'Version: v3' ``` **Node.js** ```javascript const options = { method: 'GET', headers: { Authorization: 'Bearer ', Version: 'v3' } }; try { const response = await fetch('https://services.leadconnectorhq.com/conversations/search?locationId=', options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **Python** ```python import requests url = "https://services.leadconnectorhq.com/conversations/search" headers = { "Authorization": "Bearer ", "Version": "v3" } params = { "locationId": "" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` **PHP** ```php 'https://services.leadconnectorhq.com/conversations/search?locationId=', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ', 'Version: v3', ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` **Java** ```java HttpResponse response = Unirest .get("https://services.leadconnectorhq.com/conversations/search?locationId=") .header("Authorization", "Bearer ") .header("Version", "v3") .asString(); ``` **Go** ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://services.leadconnectorhq.com/conversations/search?locationId=" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Version", "v3") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } ``` **Ruby** ```ruby require 'uri' require 'net/http' url = URI("https://services.leadconnectorhq.com/conversations/search?locationId=") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = "Bearer " request["Version"] = "v3" response = http.request(request) puts response.read_body ``` **PowerShell** ```powershell $headers = @{ "Authorization" = "Bearer " "Version" = "v3" } $response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/conversations/search?locationId=' -Method 'GET' -Headers $headers $response | ConvertTo-Json ```