List EXTERNAL Conversations
curl --request GET \
--url https://api.example.com/api/v1/sdk/conversationsimport requests
url = "https://api.example.com/api/v1/sdk/conversations"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/sdk/conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/sdk/conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/sdk/conversations"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/sdk/conversations")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/sdk/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_bodyConversations
List EXTERNAL Conversations
GET
/
api
/
v1
/
sdk
/
conversations
List EXTERNAL Conversations
curl --request GET \
--url https://api.example.com/api/v1/sdk/conversationsimport requests
url = "https://api.example.com/api/v1/sdk/conversations"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/sdk/conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/sdk/conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/sdk/conversations"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/sdk/conversations")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/sdk/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_bodyOverview
List EXTERNAL conversations where the given external user is a participant. Use this to build an inbox or “my conversations” list for SDK/external users. Preferred path:GET /api/v1/sdk/conversations (stable; no route conflict).Legacy path:
GET /api/v1/conversations/external (same behavior when server route order is correct).
Auth: Either Bearer token (SDK token from Issue SDK Token) or API keys (X-Api-Key + X-Api-Secret). With Bearer token, external_user_id is derived from the token and can be omitted.
When to Use
- Your frontend or backend needs to list conversations for a specific user (e.g. “my chats”).
- The user is identified by your app’s
external_user_id(or from tokensubwhen using Bearer).
Request Headers
| Header | Required | Description |
|---|---|---|
Authorization | Optional* | Bearer <SDK token>. Use when calling from frontend with SDK token. |
X-Api-Key | Optional* | App public key. Required when not using Bearer. |
X-Api-Secret | Optional* | App secret key. Required when not using Bearer. |
Query Parameters
| Parameter | Required | Description |
|---|---|---|
external_user_id | When using API keys | Your app’s user ID. Omit when using Bearer (backend uses token sub). |
cursor | No | Pagination cursor (ISO timestamp). |
limit | No | Page size (default 20, max 100). |
Example: Bearer token (SDK / frontend)
curl -X GET "https://dev.vocantly.com/api/v1/sdk/conversations?limit=50" \
-H "Authorization: Bearer <SDK_TOKEN>" \
-H "Content-Type: application/json"
Example: API keys (backend)
curl -X GET "https://dev.vocantly.com/api/v1/sdk/conversations?external_user_id=user_123&limit=50" \
-H "X-Api-Key: pk_xxxxx" \
-H "X-Api-Secret: sk_xxxxx"
Response
Success (200)
{
"success": true,
"message": "Conversations retrieved successfully",
"data": [
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"type": "external",
"external_id": "order_789",
"tenant_id": "...",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T12:00:00Z",
"participants": [
{ "external_user_id": "user_1", "role": "buyer", "name": "Alice", "email": "alice@example.com" },
{ "external_user_id": "user_2", "role": "seller", "name": "Bob", "email": "bob@example.com" }
]
}
]
}
updated_at descending.
Error Responses
| Status | Description |
|---|---|
| 400 | Missing external_user_id. |
| 401 | Invalid or missing X-Api-Key / X-Api-Secret. |
SDK
The JavaScript SDK calls this endpoint when you useclient.conversations.list(). Configure apiUrl and either Bearer token (same as WebSocket), API keys, or getRestHeaders(). See SDK Inbox.
Create EXTERNAL (API Key)
Create a conversation
Get EXTERNAL messages
Fetch message history