Introduction

The Replyful REST API lets you read your support data programmatically — tickets, their conversations, every message, your knowledge base Q&As, your channels, and your contacts. You can export everything stored about one person, attachments included. It also lets your own chatbot create tickets, add messages and hand over to a human agent. The API is JSON over HTTPS, follows predictable conventions, and is designed to be curl-friendly so you can prototype from the terminal before writing a single line of code.

curl https://api.replyful.com/v1/tickets?limit=1 \
  -H "Authorization: Bearer rfl_live_..."

Data model

A ticket is the case container. Every ticket has exactly one primary conversation (the thread with the requester) and zero or more side conversations (isolated threads with other parties, e.g. a supplier). Messages belong to a conversation.

ticket ─┬─ conversation (primary) ─── messages
        └─ conversation (side)    ─── messages

Base URL

https://api.replyful.com

HTTPS only — plain HTTP requests are rejected, not redirected.

Quickstart

Create an API key

In the dashboard, go to Settings → Developers → API keys and click Create key. Copy the token — it is shown once and never displayed again.

Make your first request

Replace rfl_live_... with your key and run:

curl https://api.replyful.com/v1/tickets?limit=1 \
  -H "Authorization: Bearer rfl_live_..."

Read the response

You get a list envelope with a single ticket:

{
  "object": "list",
  "data": [
    {
      "id": "ti_...",
      "object": "ticket",
      "title": "Refund request",
      "status": "open",
      "requester": {
        "id": "con_...",
        "name": "Ada Lovelace",
        "email": { "email": "[email protected]", "verified": true },
        "phone": null
      },
      "tags": [],
      "topics": [],
      "conversations": [{ "id": "conv_...", "role": "primary" }],
      "createdAt": "2026-04-29T14:30:00Z",
      "updatedAt": "2026-04-29T14:32:00Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "url": "/v1/tickets"
}

Conventions

Every endpoint in the API follows the same rules. Learn them once, apply them everywhere.

Convention	What to expect
Auth	Bearer token in the `Authorization` header. See Authentication.
Format	JSON request and response bodies. UTF-8.
Field names	`camelCase` everywhere.
Timestamps	ISO 8601 UTC strings, always with the trailing `Z` (e.g. `2026-04-29T14:32:00Z`).
IDs	Strings, usually prefixed like `ti_...`, `conv_...`, `msg_...`, `con_...`. Treat them as opaque.
Pagination	Cursor-based. See Pagination.
Errors	Status code is the source of truth. Body uses a consistent envelope. See Errors.
Rate limits	Documented headers on every response. See Rate limits.
Tracing	Every response includes a `Request-Id` header — quote it in support tickets.

What’s available today

The API is in active development. Today, the following endpoints are live:

GET /v1/tickets

List tickets with status filters, date ranges, sorting, and cursor pagination.

GET /v1/tickets/{id}

Retrieve a single ticket with all of its conversations embedded.

GET /v1/conversations/{id}/messages

Page through a conversation’s message thread, oldest first.

GET /v1/knowledge/qa

List your knowledge base Q&As — questions, variations, and answers.

GET /v1/channels

List chat widgets, email inboxes and forms with their live status and issues.

GET /v1/channels/{id}

Retrieve one channel with its AI agent, settings and configuration.

GET /v1/contacts

Find contacts by email address or your own user ID, or list them all.

GET /v1/contacts/{id}

Retrieve one contact with name, email, phone, company and data fields.

GET /v1/contacts/{id}/sessions

List a contact’s visits to the chat widget.

GET /v1/attachments/{id}/content

Download a file attached to a message.

POST /v1/tickets

Create a ticket from your own chatbot, with one message or a whole chat.

POST /v1/conversations/{id}/messages

Add a customer or chatbot message to a ticket’s conversation.

POST /v1/tickets/{id}/handover

Hand a ticket your chatbot is handling to a human agent.

More endpoints will land here as they ship. Field names, error codes, and ID prefixes are part of the public contract — they will not change without a major version bump.

Need help?

Quote the Request-Id from any response when you contact support. We keep request traces for 90 days and can pull the exact context of a failing call from that ID.

Documentation

Tickets

Channels

Conversations

Contacts

Attachments

Knowledge

Data model

Base URL

Quickstart

Conventions

What’s available today

GET /v1/tickets

GET /v1/tickets/{id}

GET /v1/conversations/{id}/messages

GET /v1/knowledge/qa

GET /v1/channels

GET /v1/channels/{id}

GET /v1/contacts

GET /v1/contacts/{id}

GET /v1/contacts/{id}/sessions

GET /v1/attachments/{id}/content

POST /v1/tickets

POST /v1/conversations/{id}/messages

POST /v1/tickets/{id}/handover

Need help?

​Data model

​Base URL

​Quickstart

​Conventions

​What’s available today

GET /v1/tickets

GET /v1/tickets/{id}

GET /v1/conversations/{id}/messages

GET /v1/knowledge/qa

GET /v1/channels

GET /v1/channels/{id}

GET /v1/contacts

GET /v1/contacts/{id}

GET /v1/contacts/{id}/sessions

GET /v1/attachments/{id}/content

POST /v1/tickets

POST /v1/conversations/{id}/messages

POST /v1/tickets/{id}/handover

​Need help?

Data model

Base URL

Quickstart

Conventions

What’s available today

Need help?