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

Parameter	Type	Required	Default	Description
platform	string	No	All platforms	Filter contacts by platform. Supported values: instagram, line, facebook, whatsapp.
limit	number	No	20	Maximum 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

Field	Type	Description
contacts	Contact[]	Array of contact objects.
total	number	Total number of contacts matching the query.
limit	number	The limit value used for this request.

Contact Object

Field	Type	Description
id	string	Unique contact identifier.
name	string	Display name of the contact.
platform	string	The messaging platform this contact belongs to.
platformUserId	string	The contact's user ID on the originating platform.
avatarUrl	string | null	URL to the contact's avatar image, or null if unavailable.
lastMessageAt	string	ISO 8601 timestamp of the most recent message from this contact.
createdAt	string	ISO 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})`);
});