💬Get free consultation

Objects and fields

Overview

Use this page when you are mapping Chatty data into something else: a helpdesk, a CRM, a warehouse table, or a spreadsheet. The Chat Conversations API page lists the paths and the parameters; this page lists what comes back inside data.

Read it before you design your own schema. Four fields never carry a value, several exist only on the single-record endpoints, and six fields accept a fixed set of values only.

Applies to	Every /chat/... response from the Chat Conversations API
Envelope	{ "data": ..., "paging": ..., "meta": ... } on list endpoints
Naming	camelCase throughout, identical from both datastores
Timestamps	ISO 8601 UTC, for example 2026-08-03T12:00:00.000Z

---

How to read these tables

Each table has four columns.

• Field — the key as it appears in the JSON.
• Type — string, boolean, integer, number, array, object, or datetime for an ISO 8601 string.
• Always present — Yes means the field is returned with a value on every endpoint that returns this object. Nullable means the field is returned but the value can be null. Detail only means only the single-record endpoint returns it; list and related endpoints omit the key entirely.
• Description — what the value means.

Treat every Nullable field as optional in your own types. A field marked Detail only will be missing, not null, when you read from a list.

---

Conversation

Returned by GET /chat/conversations, GET /chat/conversations/{id}, GET /chat/conversations/{id}/related, and GET /chat/customers/{customerUuid}/conversations. 31 documented fields. The single-record endpoint can also return internal keys that are not listed here, so ignore what you don't recognise.

Field	Type	Always present	Description
id	string	Yes	App-wide conversation id.
firestoreId	string	Nullable	The conversation's id in the older datastore.
pgConvoId	string	Nullable	The conversation's numeric id in the newer datastore.
shopId	string	Yes	Your store identifier.
sessionId	string	Nullable	Browsing session the conversation started in.
customerUuid	string	Nullable	Contact id. Pass it to GET /chat/customers/{customerUuid}.
customerName	string	Nullable	Contact name at the time of the chat.
customerEmail	string	Nullable	Contact email.
customerPhone	string	Detail only	Always null.
customerType	string	Yes	anonymous, guest, or customer.
status	string	Yes	open or resolved.
isChatBot	boolean	Yes	The conversation is currently handled by the AI agent.
hasChatBot	boolean	Yes	The AI agent took part at some point.
isRead	boolean	Yes	Read state on the agent side.
isCustomerRead	boolean	Yes	Read state on the customer side.
isOnline	boolean	Yes	The customer is connected right now.
isBlock	boolean	Yes	The customer is blocked.
isStarred	boolean	Yes	Starred in the inbox.
hasFirstMsg	boolean	Yes	The conversation carries a first message.
hidePreChatMessage	string	Yes	'', by-user, or by-admin.
memberId	string	Nullable	Assigned team member. Resolve it against GET /chat/members.
memberName	string	Detail only	Always null.
teamId	string	Detail only	Always null.
channels	array of string	Yes	Channels used in this conversation.
tags	array of string	Yes	Tags on the conversation.
messageCount	integer	Nullable	Number of messages.
unreadCount	integer	Detail only	Always 0.
lastMessage	object	Nullable	Preview of the most recent message. Fields below.
lastActive	datetime	Nullable	Last activity.
createdAt	datetime	Nullable	When the conversation started.
updatedAt	datetime	Nullable	Last update.

lastMessage

Field	Type	Always present	Description
text	string	Yes	Message text.
senderType	string	Yes	customer, agent, bot, or system. bot is the Chatty AI agent, agent is a human team member.
createdAt	datetime	Yes	When the message was sent.

Sort on lastActive rather than updatedAt when you want the newest conversations first, and expect null on both for older records. The three id fields all come back on every conversation, so you can match a record against ids you stored before your integration existed.

---

Message

Returned by GET /chat/conversations/{id}/messages and GET /chat/conversations/{id}/messages/{messageId}. 20 fields.

Field	Type	Always present	Description
id	string	Yes	Message UUID, or the numeric id when no UUID exists.
text	string	Yes	Message text.
senderName	string	Yes	Display name of the sender.
memberId	string	Nullable	Team member who sent it, when a human did.
isAdmin	boolean	Yes	Sent from the store side.
isAutomated	boolean	Yes	Sent by an automation rather than by a person.
isBot	boolean	Yes	Sent by the AI agent.
isNote	boolean	Yes	Internal note, not visible to the customer.
isFirst	boolean	Yes	First message of the conversation.
isTransfer	boolean	Yes	Marks a handover between the AI agent and a human.
isQuickReplyMsg	boolean	Yes	Sent through a quick reply.
isAskBotMessage	boolean	Yes	The customer addressed the AI agent.
isDeleted	boolean	Detail only	The message was deleted. List endpoints exclude deleted messages.
contentType	string	Detail only	text or file.
topic	string	Nullable	Topic the AI agent assigned.
chatbotProducts	array of object	Yes	Products the AI agent showed in this message.
chatbotFaqs	array of object	Yes	FAQ entries the AI agent used in this message.
files	array of object	Yes	Attachments.
replyMessage	object	Nullable	The message this one replies to.
createdAt	datetime	Yes	When the message was sent.

A message can carry keys beyond this list, so ignore what you don't recognise rather than rejecting the record.

To reconcile deletions against your own copy, read the single message: it returns the record with "isDeleted": true, while the list endpoint simply stops returning it. Use contentType to word your own placeholder for a deleted message.

---

Customer

Returned by GET /chat/customers/{customerUuid}. This is the contact profile the widget collects, merged with what the Shopify sync provides. 30 fields.

Field	Type	Always present	Description
id	string	Yes	Contact id. Matches customerUuid on a conversation.
shopifyId	string	Nullable	Matching Shopify customer id.
name	string	Nullable	Display name.
firstName	string	Nullable	First name.
lastName	string	Nullable	Last name.
email	string	Nullable	Email address.
phone	string	Nullable	Phone number.
type	string	Yes	anonymous, guest, or customer.
channels	array of string	Yes	Channels the contact has used.
tags	array of string	Nullable	Tags on the contact.
note	string	Nullable	Free-text note on the contact.
customAttributes	object	Nullable	Key/value pairs pushed by the storefront widget. Values are strings.
address1	string	Nullable	Address line 1.
address2	string	Nullable	Address line 2.
city	string	Nullable	City.
zip	string	Nullable	Postal code.
country	string	Nullable	Country name.
countryCode	string	Nullable	Country code.
ordersCount	integer	Nullable	Number of orders placed.
totalSpent	number	Nullable	Lifetime spend.
ipAddress	string	Nullable	Last seen IP address.
ipLocation	string	Nullable	Location derived from the IP address.
browser	string	Nullable	Browser name.
browserVersion	string	Nullable	Browser version.
os	string	Nullable	Operating system.
deviceType	string	Nullable	Device type.
senderSeq	integer	Nullable	Sequence number of the contact as a sender.
lastChatAt	datetime	Nullable	Last time the contact chatted.
createdAt	datetime	Yes	When the contact was first seen.
updatedAt	datetime	Nullable	Last update.

id, type, channels, and createdAt are the only fields that always carry a value. Everything else depends on what the visitor gave you, so an anonymous visitor produces a profile that is mostly null.

---

Member

Returned by GET /chat/members and GET /chat/members/{memberId}. 10 fields. Credentials, tokens, and notification internals are never exposed.

Field	Type	Always present	Description
id	string	Yes	Team member id. Matches memberId on conversations and messages.
email	string	Yes	Work email.
firstName	string	Nullable	First name.
lastName	string	Nullable	Last name.
fullName	string	Yes	Full name.
avatarUrl	string	Yes	Avatar image URL.
role	string	Yes	admin or member.
active	boolean	Yes	The member is active.
enableAwayMode	boolean	Nullable	Away mode is switched on.
createdAt	datetime	Yes	When the member was added.

Cache this list. Conversations and messages carry memberId only, so every agent name in your own interface comes from here.

---

Note

Returned by the note endpoints under /chat/conversations/{id}/notes. 5 fields.

Field	Type	Always present	Description
id	string	Yes	Note id. Use it on update and delete.
text	string	Yes	Note text, up to 150 characters.
isUpdated	boolean	Yes	The note was edited after it was created.
createdAt	datetime	Yes	When the note was created.
updatedAt	datetime	Yes	When the note was last changed.

---

Attribute

Returned by the attribute endpoints under /chat/conversations/{id}/attributes. 5 fields.

Field	Type	Always present	Description
id	string	Yes	Attribute id. Use it on update and delete.
name	string	Yes	Attribute name, up to 255 characters. Writes upsert by name.
value	string	Yes	Attribute value, up to 1000 characters.
createdAt	datetime	Yes	When the attribute was created.
updatedAt	datetime	Yes	When the attribute was last changed.

---

Webhook subscription

Returned by the webhook endpoints under /chat/webhooks. 9 fields. Once a subscription has attempted its first delivery it also carries lastDeliveryAt, lastDeliveryStatus, and lastDeliveryError. For the events themselves and for signature verification, see Webhooks.

Field	Type	Always present	Description
id	string	Yes	Subscription id. Use it on update and delete.
shopId	string	Yes	Your store identifier.
url	string	Yes	Endpoint Chatty posts events to.
events	array of string	Yes	Events this subscription receives.
isActive	boolean	Yes	The subscription is delivering.
secret	string	Yes	Signing secret used to verify each delivery.
metadata	object	Yes	Your own key/value data on the subscription.
createdAt	datetime	Yes	When the subscription was created.
updatedAt	datetime	Yes	When the subscription was last changed.

---

Fixed value sets

Six fields accept a fixed set of values. Compare against the exact lowercase strings below.

• customerType on a conversation and type on a contact: anonymous, guest, customer
• status on a conversation: open, resolved
• hidePreChatMessage on a conversation: '' (empty string), by-user, by-admin
• senderType inside lastMessage: customer, agent, bot, system
• contentType on a message: text, file
• role on a member: admin, member

A seventh sits in the envelope rather than on an object: meta.source reports which datastore served the read, postgresql or firestore. It's diagnostic. The field names and shapes above are identical either way, so don't branch your parsing on it.

Treat an unrecognised value as a value you haven't seen yet, not as an error. New entries can be added to any of these sets.

---

Need help?

Contact the Chatty support team from your dashboard. Include the endpoint, the timestamp of the request, and the field you're asking about.

For the paths, parameters, and rate limits that go with these objects, see the Chat Conversations API. For contact data over GraphQL, see the GraphQL Customer API.