Messages · Docs

Conversations between an account and the creators it works with. Everything an inbox needs is in the API, so you can build your own.

Start a conversation

POST /v1/threads opens a direct conversation with a creator you work with, or returns the existing one. Include a first message if you like:

TypeScript

const { data: thread } = await lucra.threads.create({
  body: { kind: "direct", with: "crtr_06ZqNevhUeDnqxzC6VkeuQr", message: { body: "Welcome aboard!" } },
})

kind: "program" opens a program's group chat instead, with program set to its ID.

Read and reply

GET /v1/threads lists conversations, most recently active first. GET /v1/messages?thread=thr_… reads one. Reply with POST /v1/messages:

TypeScript

await lucra.messages.create({ body: { thread: thread.id, body: "Loved the first cut!" } })

PATCH /v1/messages/:id edits or deletes a message you sent (send its version), sets a reaction like { "reaction": { "emoji": "🎉", "active": true } }, or reports a message. One change per request.

Notes

A partner does all of this as a roster creator with Lucra-Account: crtr_….
The message.created webhook tells you when a message arrives.
Read state, muting and live updates are yours to keep in your own app: track what each of your users has seen by message ID.

Endpoints

GET/v1/messages

As creatorread

List messages

const { data } = await lucra.messages.list({
  query: { thread: "thr_…" },
})

Query parameters

threadthr_…

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 12 fields each, and nextCursorShow

idstring
threadstring
senderobject
Show 4 child fieldsHide child fields
- idstring
- typeenum
  organizationcreatorsupport
- namestringnullable
- avatarstringnullable
automatedboolean
bodystring
filesobject[]
Show 8 child fieldsHide child fields
- idstring
- namestring
- kindenum
  imagevideodocument
- sizenumbernullable
- widthnumbernullable
- heightnumbernullable
- urlstringnullable
- thumbnailUrlstringnullable
replyTostringnullable
reactionsobject[]
Show 2 child fieldsHide child fields
- emojistring
- actorsstring[]
createdAtstring
editedAtstringnullable
deletedAtstringnullable
versioninteger

POST/v1/messages

As creatorwrite

Send a message

const { data } = await lucra.messages.create({
  body: { thread: "thr_…" },
})

Body

threadthr_…· required
bodystring
filesfile_…[]
Attachments: chat_attachment files.
replyTomsg_…

Response20112 fieldsShow

idstring
threadstring
senderobject
Show 4 child fieldsHide child fields
- idstring
- typeenum
  organizationcreatorsupport
- namestringnullable
- avatarstringnullable
automatedboolean
bodystring
filesobject[]
Show 8 child fieldsHide child fields
- idstring
- namestring
- kindenum
  imagevideodocument
- sizenumbernullable
- widthnumbernullable
- heightnumbernullable
- urlstringnullable
- thumbnailUrlstringnullable
replyTostringnullable
reactionsobject[]
Show 2 child fieldsHide child fields
- emojistring
- actorsstring[]
createdAtstring
editedAtstringnullable
deletedAtstringnullable
versioninteger

PATCH/v1/messages/:id

As creatorwrite

Edit or delete a message the caller sent (at its version), react to a message, or report it; one change per request

const { data } = await lucra.messages.update({
  path: { id: "…" },
  body: { version: 1000 },
})

Path parameters

idstring· required

Body

versioninteger
The message's version as read; required to edit or delete.
bodystring
New text for a message the caller sent.
statusstring
Delete a message the caller sent.
deleted
reactionobject
Add or remove the caller's emoji reaction.
Show 2 child fieldsHide child fields
- emojistring· required
- activeboolean· required
  true adds the reaction, false removes it.
reportobject
Report the message to Lucra.
Show 2 child fieldsHide child fields
- reasonenum· required
  spamharassmentunsafe_contentother
- detailstring

Response20012 fieldsShow

idstring
threadstring
senderobject
Show 4 child fieldsHide child fields
- idstring
- typeenum
  organizationcreatorsupport
- namestringnullable
- avatarstringnullable
automatedboolean
bodystring
filesobject[]
Show 8 child fieldsHide child fields
- idstring
- namestring
- kindenum
  imagevideodocument
- sizenumbernullable
- widthnumbernullable
- heightnumbernullable
- urlstringnullable
- thumbnailUrlstringnullable
replyTostringnullable
reactionsobject[]
Show 2 child fieldsHide child fields
- emojistring
- actorsstring[]
createdAtstring
editedAtstringnullable
deletedAtstringnullable
versioninteger

GET/v1/threads

As creatorread

List the conversations the account (or, acting as a creator, the creator) takes part in, most recently active first

const { data } = await lucra.threads.list({
  query: { kind: "direct" },
})

Query parameters

kindenum
directprogramsupport
programprog_…

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 15 fields each, and nextCursorShow

idstring
kindenum
directprogramsupport
accountstringnullable
programstringnullable
programNamestringnullable
supportobjectnullable
Show 2 child fieldsHide child fields
- statusenum
  waiting_on_lucrawaiting_on_customerresolved
- resolvedAtstringnullable
participantsobject[]
Show 3 child fieldsHide child fields
- actorobject
  Show 4 child fieldsHide child fields
  idstring
  typeenum
  organizationcreatorsupport
  namestringnullable
  avatarstringnullable
- lastReadstringnullable
- joinedAtstring
lastMessageobjectnullable
Show 12 child fieldsHide child fields
- idstring
- threadstring
- senderobject
  Show 4 child fieldsHide child fields
  idstring
  typeenum
  organizationcreatorsupport
  namestringnullable
  avatarstringnullable
- automatedboolean
- bodystring
- filesobject[]
  Show 8 child fieldsHide child fields
  idstring
  namestring
  kindenum
  imagevideodocument
  sizenumbernullable
  widthnumbernullable
  heightnumbernullable
  urlstringnullable
  thumbnailUrlstringnullable
- replyTostringnullable
- reactionsobject[]
  Show 2 child fieldsHide child fields
  emojistring
  actorsstring[]
- createdAtstring
- editedAtstringnullable
- deletedAtstringnullable
- versioninteger
mutedboolean
blockedstring[]
canSendboolean
unreadCountinteger
createdAtstring
updatedAtstring
versioninteger

POST/v1/threads

As creatorwrite

Open a direct conversation with an account or creator you work with (an account can also message any creator it finds in the marketplace), a program's group chat or a Lucra Support thread; an existing one is returned

const { data } = await lucra.threads.create({
  body: { kind: "direct" },
})

Body

kindenum· required
direct: one account or creator; program: a program's group chat; support: Lucra Support.
directprogramsupport
withstring
direct: the account (acct_) or creator (crtr_) to talk to; a creator must work with the account (and the reverse).
programstring
program: the program (prog_) whose group chat to open.
messageobject
A first message, sent when the conversation is new.
Show 2 child fieldsHide child fields
- bodystring
  The message text.
- filesstring[]
  Attachments: chat_attachment files (file_).

Response20115 fieldsShow

idstring
kindenum
directprogramsupport
accountstringnullable
programstringnullable
programNamestringnullable
supportobjectnullable
Show 2 child fieldsHide child fields
- statusenum
  waiting_on_lucrawaiting_on_customerresolved
- resolvedAtstringnullable
participantsobject[]
Show 3 child fieldsHide child fields
- actorobject
  Show 4 child fieldsHide child fields
  idstring
  typeenum
  organizationcreatorsupport
  namestringnullable
  avatarstringnullable
- lastReadstringnullable
- joinedAtstring
lastMessageobjectnullable
Show 12 child fieldsHide child fields
- idstring
- threadstring
- senderobject
  Show 4 child fieldsHide child fields
  idstring
  typeenum
  organizationcreatorsupport
  namestringnullable
  avatarstringnullable
- automatedboolean
- bodystring
- filesobject[]
  Show 8 child fieldsHide child fields
  idstring
  namestring
  kindenum
  imagevideodocument
  sizenumbernullable
  widthnumbernullable
  heightnumbernullable
  urlstringnullable
  thumbnailUrlstringnullable
- replyTostringnullable
- reactionsobject[]
  Show 2 child fieldsHide child fields
  emojistring
  actorsstring[]
- createdAtstring
- editedAtstringnullable
- deletedAtstringnullable
- versioninteger
mutedboolean
blockedstring[]
canSendboolean
unreadCountinteger
createdAtstring
updatedAtstring
versioninteger

GET/v1/threads/:id

As creatorread

Get a conversation; its messages are GET /v1/messages?thread=

const { data } = await lucra.threads.retrieve({
  path: { id: "…" },
})

Path parameters

idstring· required

Response20015 fieldsShow

idstring
kindenum
directprogramsupport
accountstringnullable
programstringnullable
programNamestringnullable
supportobjectnullable
Show 2 child fieldsHide child fields
- statusenum
  waiting_on_lucrawaiting_on_customerresolved
- resolvedAtstringnullable
participantsobject[]
Show 3 child fieldsHide child fields
- actorobject
  Show 4 child fieldsHide child fields
  idstring
  typeenum
  organizationcreatorsupport
  namestringnullable
  avatarstringnullable
- lastReadstringnullable
- joinedAtstring
lastMessageobjectnullable
Show 12 child fieldsHide child fields
- idstring
- threadstring
- senderobject
  Show 4 child fieldsHide child fields
  idstring
  typeenum
  organizationcreatorsupport
  namestringnullable
  avatarstringnullable
- automatedboolean
- bodystring
- filesobject[]
  Show 8 child fieldsHide child fields
  idstring
  namestring
  kindenum
  imagevideodocument
  sizenumbernullable
  widthnumbernullable
  heightnumbernullable
  urlstringnullable
  thumbnailUrlstringnullable
- replyTostringnullable
- reactionsobject[]
  Show 2 child fieldsHide child fields
  emojistring
  actorsstring[]
- createdAtstring
- editedAtstringnullable
- deletedAtstringnullable
- versioninteger
mutedboolean
blockedstring[]
canSendboolean
unreadCountinteger
createdAtstring
updatedAtstring
versioninteger