List Conversations

The Messages API is a unified inbox for direct messages. A conversation is a DM thread with one participant on a connected account; messages belong to a conversation. Conversations are stored by Socialit so you can list and search them.

Sending goes through the platform, so a platform without DM support returns 403 { "error": "not_supported", "capability": "messages" }. Supported on: meta, instagram, x (legacy DMs), bluesky, google_business (limited).

The conversation object

{
  "id": "conv_5kM...",
  "platform": "instagram",
  "account_id": "sa_...",
  "participant_id": "178...",
  "participant_name": "Jane",
  "participant_username": "jane",
  "participant_avatar_url": "https://...",
  "status": "active",
  "last_message": "Hey!",
  "unread_count": 1,
  "updated_at": "2026-07-12T08:30:00.000Z",
  "created_at": "2026-07-10T08:30:00.000Z"
}

GET/v1/conversations

Filter with ?profile_id=, ?account_id=, or ?status=active|archived.

{
  "conversations": [
    {
      "id": "conv_5kM...",
      "platform": "instagram",
      "account_id": "sa_...",
      "participant_id": "178...",
      "participant_name": "Jane",
      "participant_username": "jane",
      "participant_avatar_url": "https://...",
      "status": "active",
      "last_message": "Hey!",
      "unread_count": 1,
      "updated_at": "2026-07-12T08:30:00.000Z",
      "created_at": "2026-07-10T08:30:00.000Z"
    }
  ]
}

Open a Conversation

POST/v1/conversations

POST /v1/conversations

curl -X POST https://api.socialit.com/v1/conversations \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "sa_...", "participant_id": "178...", "message": "Hi there!" }'

{
  "conversation": {
    "id": "conv_5kM...",
    "platform": "instagram",
    "account_id": "sa_...",
    "participant_id": "178...",
    "participant_name": "Jane",
    "participant_username": "jane",
    "participant_avatar_url": "https://...",
    "status": "active",
    "last_message": "Hey!",
    "unread_count": 1,
    "updated_at": "2026-07-12T08:30:00.000Z",
    "created_at": "2026-07-10T08:30:00.000Z"
  }
}

List Messages

You can also fetch a single conversation with GET /v1/conversations/:id.

GET/v1/conversations/:id/messages

{
  "messages": [
    { "id": "msg_...", "direction": "in", "text": "Hey!", "attachments": [], "sent_at": "2026-07-12T08:30:00.000Z" }
  ]
}

Send a Message

POST/v1/conversations/:id/messages

Body fields: account_id, message, optional attachment_url.

POST /v1/conversations/:id/messages

curl -X POST https://api.socialit.com/v1/conversations/conv_5kM.../messages \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "sa_...", "message": "Hi there!" }'

{ "message": { "id": "msg_...", "direction": "out", "text": "Hi there!", "attachments": [], "sent_at": "2026-07-12T08:31:00.000Z" } }

Typing indicator

POST /v1/conversations/:id/typing sends a typing indicator for the conversation.

POST /v1/conversations/:id/typing

curl -X POST https://api.socialit.com/v1/conversations/conv_5kM.../typing \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "sa_..." }'

{
  "ok": true
}

Reactions

Add a reaction

POST/v1/messages/:id/reactions

POST /v1/messages/:id/reactions

curl -X POST https://api.socialit.com/v1/messages/msg_.../reactions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "sa_...", "emoji": "👍" }'

{
  "ok": true
}

Remove a reaction

DELETE/v1/messages/:id/reactions

{
  "ok": true
}