Home Docs Senders API

Senders API

Read the contacts a campaign has engaged with, along with their per-contact state.

"Senders" is the umbrella term for everyone a campaign has touched — inbound senders in auto-reply mode, outbound recipients in broadcast mode. The endpoint is read-only; contacts are created implicitly by inbound messages or by CSV import in the dashboard.

List senders

GET /api/v1/campaigns/{id}/senders — requires senders:read.

curl "https://prime-bot.live/api/v1/campaigns/1/senders?per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Query parameters

Name	Default	Description
`per_page`	25	Page size, capped at 100.
`page`	1	1-indexed page number.
`status`	(none)	Filter by delivery state: `pending`, `sent`, `replied`, `failed`.
`q`	(none)	Case-insensitive substring match on first name, last name, or handle.

Response shape

{
  "data": [
    {
      "id": 904,
      "campaign_id": 1,
      "telegram_user_id": 51209117,
      "handle": "@janedoe",
      "first_name": "Jane",
      "last_name": "Doe",
      "status": "replied",
      "last_message_at": "2026-04-21T16:02:41Z",
      "last_reply_at": "2026-04-21T16:03:08Z",
      "tags": ["vip", "paid"]
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total": 312,
      "last_page": 7
    }
  }
}

Status field

pending — queued for a broadcast send but not yet dispatched.
sent — at least one message was delivered, no reply yet.
replied — the contact replied; any active sequence is now paused for them.
failed — Telegram rejected the send (privacy settings, deactivated account, etc.). See the matching entry in Logs for the error.

Notes

Tags are defined in the dashboard and come back as a flat array of strings — they're useful for segmenting your own exports.
Phone numbers are never returned for privacy reasons; use telegram_user_id as the stable identifier.

Edit this page on GitHub Last updated Jun 17, 2026