Create a ticket

Creates a ticket on one of your chat channels, handled by AI (your bot) until you hand it over. Send one message to start a live chat, or the whole transcript at once. See Bring your own chatbot for the full flow.

POST /v1/tickets

Authentication

A Read & write live key. See Authentication.

Body

string

required

One of your chat channels. It decides which teams see the ticket and where a handover goes.

array

required

1 to 100 messages, oldest first. The first must have role: "user".

Show properties

string

required

user (the customer) or assistant (your bot).

string

required

Plain text, up to 20,000 characters.

string

ISO 8601 time the message was written, in UTC (2026-11-10T09:14:02Z) or with an offset (2026-11-10T10:14:02+01:00). Defaults to now. Cannot be in the future. Send it on every message or on none, oldest first.

string

Your own ID for the chat, up to 128 characters. Unique per organization: a second ticket with the same ID returns 409 ticket_external_id_taken.

object

Who the customer is. Leave it out for an anonymous visitor.

Show properties

string

Your user ID. Finds or creates the one contact for that user.

string

First name.

string

Last name.

object

Show properties

string

required

The email address.

boolean

true when you have checked that the person owns the address, so personal data may be sent there. Defaults to false. Must be true when you also send externalId: leave the email out for a user whose address you have not checked.

string

A Replyful contact ID (requester.id from an earlier ticket) to reuse that contact. Send it on its own.

Unknown fields are refused with 400 unknown_field.

Response

201 with the Ticket object, including its conversations. Post further messages to the conversation with role: "primary".

Example

curl https://api.replyful.com/v1/tickets \
  -H "Authorization: Bearer rfl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9c7f1ad1-6c4f-4d4d-bfde-3b1e6e1c8f5a" \
  -d '{
    "channelId": "k3Jd82La",
    "externalId": "chat-8812",
    "requester": {
      "externalId": "user_42",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": { "email": "[email protected]", "verified": true }
    },
    "messages": [
      { "role": "user", "content": "My invoice is wrong" },
      { "role": "assistant", "content": "Let me check that for you." }
    ]
  }'

const res = await fetch("https://api.replyful.com/v1/tickets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REPLYFUL_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    channelId: "k3Jd82La",
    externalId: "chat-8812",
    requester: { externalId: "user_42", firstName: "Ada", lastName: "Lovelace" },
    messages: [{ role: "user", content: "My invoice is wrong" }],
  }),
});
const ticket = await res.json();
const conversationId = ticket.conversations[0].id;

Response

{
  "id": "ti_8kNwq2Tt7yGkX9wM4bDfP",
  "object": "ticket",
  "externalId": "chat-8812",
  "title": "My invoice is wrong",
  "status": "open",
  "handledBy": "ai",
  "requester": {
    "id": "con_9dKmT3xWq6bYrN8cJfA2eH4gp",
    "externalId": "user_42",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "name": "Ada Lovelace",
    "email": { "email": "[email protected]", "verified": true },
    "phone": null
  },
  "conversations": [
    { "id": "conv_4tGh7Kq2Lm9Zx1B", "object": "conversation", "role": "primary", "status": "waiting_for_user" }
  ]
}

The response is shortened here; it carries every field of the ticket object.

Errors

Status	Code	Meaning
`403`	`write_access_required`	The key is read-only.
`403`	`test_mode_write_not_supported`	Test keys cannot write yet.
`409`	`ticket_external_id_taken`	A ticket with this `externalId` exists. The message names it.
`422`	`invalid_channel`	`channelId` is not one of your chat channels.
`422`	`requester_not_found`	`requester.id` matches no contact.
`422`	`invalid_body`	A field failed validation. `param` names it.

Documentation

Tickets

Channels

Conversations

Contacts

Attachments

Knowledge

Authentication

Body

Response

Example

Errors

​Authentication

​Body

​Response

​Example

​Errors

Authentication

Body

Response

Example

Errors