Fetch a contact's messages

fetch a contact's messages. Returns the most recent messages across every channel and conversation for the contact, in chronological order (oldest → newest).

GET https://api.centerfy.ai/webhooks/inbound/contacts/:id/messages

Headers

Header	Required	Value	Description
`x-api-key`	Yes	your sub-account API key (cfy_…)	authenticates the request; or pass Authorization: Bearer `<key>`.

Path parameters

Name	Type	Required	Description
`id`	`string (uuid)`	Yes	the contact id. A non-uuid returns 400; a contact that does not exist returns 404.

Query parameters

Name	Type	Required	Default	Description
`limit`	`integer`	No	`100`	max number of most-recent messages to return; min 1, max 500 (values above 500 are clamped to 500). Defaults to 100 when omitted or invalid.
`channel`	`string`	No	—	optional filter by channel (e.g. sms, whatsapp, facebook, instagram). Case-insensitive.

Example

curl -X GET "https://api.centerfy.ai/webhooks/inbound/contacts/{id}/messages?limit=100" \
  -H "x-api-key: $CENTERFY_API_KEY"

import { CenterfyClient } from "@centerfy/sdk";

const centerfy = new CenterfyClient({ apiKey: process.env.CENTERFY_API_KEY! });

const result = await centerfy.messages.listForContact("<contactId>", {
  "limit": 100
});
console.log(result);

centerfy messages list-for-contact <contactId> '{"limit":100}'

MCP tool: centerfy_messages_list_for_contact (see MCP server)

Response

{
  "status": "success",
  "contact_id": "7f1c9e2a-3b4d-4e5f-8a90-1b2c3d4e5f60",
  "message_count": 2,
  "messages": [
    {
      "id": "a1b2c3d4-0001-4abc-9def-000000000001",
      "channel": "sms",
      "direction": "inbound",
      "sender_type": "contact",
      "content": "Hi, is anyone available?",
      "attachment_urls": [],
      "timestamp": "2026-06-12T14:30:00.000Z"
    },
    {
      "id": "a1b2c3d4-0002-4abc-9def-000000000002",
      "channel": "sms",
      "direction": "outbound",
      "sender_type": "ai",
      "content": "Hi! Yes, how can I help you today?",
      "attachment_urls": [],
      "timestamp": "2026-06-12T14:30:45.000Z"
    }
  ]
}

Errors

401 — if unauthenticated; 400 for an invalid contact id; 404 if the contact does not exist; When the contact has no conversations, returns message_count 0 and an empty messages array. direction is ‘inbound’ for messages from the contact, otherwise ‘outbound’.

Notes

Read-only.