メインコンテンツまでスキップ

Contacts

Retrieve a unified list of contacts across all connected messaging platforms, including Instagram, LINE, and others.

Endpoint​

GET /v1/contacts

Authentication​

Requires a valid API key via the X-API-Key header.

Parameters​

ParameterTypeRequiredDefaultDescription
platformstringNoAll platformsFilter contacts by platform. Supported values: instagram, line, facebook, whatsapp.
limitnumberNo20Maximum number of contacts to return. Max value: 100.

Request Example​

curl​

curl -X GET "https://api.convotic.com/v1/contacts?platform=instagram&limit=10" \
-H "X-API-Key: your-api-key-here"

Response Example​

{
"contacts": [
{
"id": "ct_abc123",
"name": "Somchai Prasert",
"platform": "instagram",
"platformUserId": "ig_44821937",
"avatarUrl": "https://cdn.convotic.com/avatars/ct_abc123.jpg",
"lastMessageAt": "2026-03-30T14:22:00Z",
"createdAt": "2026-01-15T09:00:00Z"
},
{
"id": "ct_def456",
"name": "Arisara Kongkaew",
"platform": "line",
"platformUserId": "line_u8832a1c",
"avatarUrl": "https://cdn.convotic.com/avatars/ct_def456.jpg",
"lastMessageAt": "2026-03-29T11:05:00Z",
"createdAt": "2026-02-03T16:30:00Z"
},
{
"id": "ct_ghi789",
"name": "Natthapong Suwan",
"platform": "instagram",
"platformUserId": "ig_55934821",
"avatarUrl": null,
"lastMessageAt": "2026-03-28T08:17:00Z",
"createdAt": "2026-03-01T12:00:00Z"
}
],
"total": 142,
"limit": 10
}

Response Fields​

FieldTypeDescription
contactsContact[]Array of contact objects.
totalnumberTotal number of contacts matching the query.
limitnumberThe limit value used for this request.

Contact Object​

FieldTypeDescription
idstringUnique contact identifier.
namestringDisplay name of the contact.
platformstringThe messaging platform this contact belongs to.
platformUserIdstringThe contact's user ID on the originating platform.
avatarUrlstring | nullURL to the contact's avatar image, or null if unavailable.
lastMessageAtstringISO 8601 timestamp of the most recent message from this contact.
createdAtstringISO 8601 timestamp of when the contact was first seen.

TypeScript Example​

interface Contact {
id: string;
name: string;
platform: string;
platformUserId: string;
avatarUrl: string | null;
lastMessageAt: string;
createdAt: string;
}

interface ContactsResponse {
contacts: Contact[];
total: number;
limit: number;
}

const params = new URLSearchParams({
platform: "instagram",
limit: "10",
});

const response = await fetch(
`https://api.convotic.com/v1/contacts?${params}`,
{
headers: {
"X-API-Key": "your-api-key-here",
},
}
);

const data: ContactsResponse = await response.json();
console.log(`Found ${data.total} contacts`);
data.contacts.forEach((contact) => {
console.log(`${contact.name} (${contact.platform})`);
});