Skip to main content
Helpwing Docs
Start free

API reference

The 25 operations a project API key can call, generated from the API itself. For what any of it is for, start with the guide.

← The REST API guide The same thing as an OpenAPI document

Reading a path

Every path below is relative to https://api.helpwing.app/api/v1 and takes the same two or three ids, so they are not repeated under each operation: {project_pk} is your project, {ticket_pk} the ticket a message belongs to, and {id} the object the path itself names. Send every request with Authorization: Api-Key ….

Tickets and messages

List tickets

GET/projects/{project_pk}/tickets/

The ticket list column of the inbox. Combine view with search, status, priority, source, assignee and tag, and sort with ordering.

Query

assigneestring (uuid)
—
created_afterstring (date-time)
—
created_beforestring (date-time)
—
customerstring (uuid)
—
inboxstring (uuid)
—
is_spamboolean
—
orderingstring
Sort field. Prefix with `-` to reverse. Default `-last_message_at`.One of-created_at, -last_message_at, -priority, created_at, last_message_at, priority
pageinteger
A page number within the paginated result set.
page_sizeinteger
Number of results to return per page.
prioritystring
* `low` - Low * `normal` - Normal * `high` - High * `urgent` - UrgentOne ofhigh, low, normal, urgent
searchstring
A search term.
sourcestring
* `email` - Email * `chat` - Chat * `api` - API * `portal` - PortalOne ofapi, chat, email, portal
statusstring[]
* `open` - Open * `pending` - Pending * `resolved` - Resolved * `closed` - Closed
tagstring
—
unassignedboolean
—
viewstring
Named inbox view: my_open, unassigned, all_open, pending, resolved, closed, mentioned, spam.

Responses

Create ticket

POST/projects/{project_pk}/tickets/

Creates a ticket and, when a body is supplied, its first customer message. Server-to-server callers authenticated with an API key should send source: api.

Body

subjectstringrequired
—
prioritystring
One oflow, normal, high, urgent
sourcestring
One ofemail, chat, api, portal
inboxstring (uuid)| null
—
external_refstring
Your own identifier, set when creating tickets over the API.
metadataobject
—
customer_idstring (uuid)
Existing customer in this project.
customer_emailstring (email)
Creates or reuses a customer by email.
customer_namestring
—
customer_external_idstring
—
body_textstring
First customer message.
body_htmlstring
—
tag_idsstring (uuid)[]
—

Responses

Get ticket

GET/projects/{project_pk}/tickets/{id}/

Full ticket for the conversation workspace, including current viewers.

Responses

Replace ticket

PUT/projects/{project_pk}/tickets/{id}/

Tickets of one project.

Body

subjectstringrequired
—
statusstring
One ofopen, pending, resolved, closed
prioritystring
One oflow, normal, high, urgent
sourcestring
One ofemail, chat, api, portal
inboxstring (uuid)| null
—
is_spamboolean
—
external_refstring
Your own identifier, set when creating tickets over the API.
email_thread_idstring
—
metadataobject
—

Responses

Update ticket

PATCH/projects/{project_pk}/tickets/{id}/

Subject, priority, spam flag and metadata. Use the dedicated actions for status, assignee and tags.

Body

subjectstring
—
statusstring
One ofopen, pending, resolved, closed
prioritystring
One oflow, normal, high, urgent
sourcestring
One ofemail, chat, api, portal
inboxstring (uuid)| null
—
is_spamboolean
—
external_refstring
Your own identifier, set when creating tickets over the API.
email_thread_idstring
—
metadataobject
—

Responses

Delete ticket

DELETE/projects/{project_pk}/tickets/{id}/

Tickets of one project.

Responses

  • 204 — no body · No response body

Assign ticket

POST/projects/{project_pk}/tickets/{id}/assign/

Assign to a member of the organization, or send assignee_id: null to unassign.

Body

assignee_idstring (uuid)| null
—

Responses

Append inbound customer message

POST/projects/{project_pk}/tickets/{id}/inbound/

Adds a message authored by the customer, as an inbound email or a chat message would. Reopens the ticket when the project has reopen_on_customer_reply enabled.

Body

body_textstring
—
body_htmlstring
—
sourcestring
One ofemail, chat, api, portal

Responses

Merge ticket

POST/projects/{project_pk}/tickets/{id}/merge/

Moves every message of this ticket into the target ticket, closes this one and links it with merged_into. Irreversible.

Body

target_ticket_idstring (uuid)required
—

Responses

Change ticket priority

POST/projects/{project_pk}/tickets/{id}/priority/

Tickets of one project.

Body

prioritystringrequired
One oflow, normal, high, urgent

Responses

Change ticket status

POST/projects/{project_pk}/tickets/{id}/status/

Open, pending, resolved or closed. Moving a resolved or closed ticket back to open records a reopened activity entry.

Body

statusstringrequired
One ofopen, pending, resolved, closed

Responses

Set ticket tags

PUT/projects/{project_pk}/tickets/{id}/tags/

Replaces the full tag set of the ticket.

Body

tag_idsstring (uuid)[]required
—

Responses

Mark as spam or not spam

POST/projects/{project_pk}/tickets/{id}/toggle-spam/

Tickets of one project.

Responses

List messages

GET/projects/{project_pk}/tickets/{ticket_pk}/messages/

The conversation, oldest first: customer messages, agent replies, internal notes and system entries.

Query

delivery_statusstring
* `not_applicable` - Not applicable * `queued` - Queued * `sent` - Sent * `delivered` - Delivered * `bounced` - Bounced * `failed` - FailedOne ofbounced, delivered, failed, not_applicable, queued, sent
kindstring
* `customer` - Customer message * `reply` - Agent reply * `note` - Internal note * `system` - System messageOne ofcustomer, note, reply, system
orderingstring
Which field to use when ordering the results.
pageinteger
A page number within the paginated result set.
page_sizeinteger
Number of results to return per page.
searchstring
A search term.

Responses

Reply or add internal note

POST/projects/{project_pk}/tickets/{ticket_pk}/messages/

Post as JSON, or as multipart with one files part per attachment. Attachments belong in this request: a reply's delivery is queued the moment it commits, so a file uploaded afterwards misses the email it should have left with.

Body — JSON, or multipart to attach files

kindstring
One ofreply, note
body_htmlstring
—
body_textstring
—
mentioned_user_idsstring (uuid)[]
Members @-mentioned in a note.
filesstring (binary)[]
Files to attach, as multipart. Attached before the reply is queued, so they leave with the email.

Responses

Get message

GET/projects/{project_pk}/tickets/{ticket_pk}/messages/{id}/

Messages of one ticket.

Responses

Mark reply as bounced

POST/projects/{project_pk}/tickets/{ticket_pk}/messages/{id}/bounce/

Simulates or records a delivery failure reported by the mail provider.

Responses

Bulk update tickets

POST/projects/{project_pk}/tickets/bulk/

Applies status, priority, assignee, tag or spam changes to many tickets at once.

Body

ticket_idsstring (uuid)[]required
—
statusstring
One ofopen, pending, resolved, closed
prioritystring
One oflow, normal, high, urgent
assignee_idstring (uuid)| null
—
add_tag_idsstring (uuid)[]
—
remove_tag_idsstring (uuid)[]
—
is_spamboolean
—

Responses

Customers

List customers

GET/projects/{project_pk}/customers/

Searchable, filterable customer directory for one project.

Query

has_open_ticketsboolean
—
is_anonymizedboolean
—
is_blockedboolean
—
is_identity_verifiedboolean
—
orderingstring
Which field to use when ordering the results.
pageinteger
A page number within the paginated result set.
page_sizeinteger
Number of results to return per page.
planstring
—
searchstring
A search term.
seen_afterstring (date-time)
—
seen_beforestring (date-time)
—
tagstring
Tag slug.

Responses

Create customer

POST/projects/{project_pk}/customers/

Customers of one project.

Body

namestring
—
emailstring (email)
—
external_idstring
Your application's user id, passed to Support.identify().
avatar_urlstring (uri)
—
planstring
Plan reported by your app, e.g. pro.
browserstring
—
operating_systemstring
—
current_pagestring (uri)
—
localestring
—
timezonestring
—
metadataobject
Free-form JSON sent from your app. Shown in the customer panel.
tag_idsstring (uuid)[]
—
first_seen_atstring (date-time)
—
last_seen_atstring (date-time)
—
is_blockedboolean
—

Responses

Get customer

GET/projects/{project_pk}/customers/{id}/

Full profile including custom metadata and ticket counters.

Responses

Replace customer

PUT/projects/{project_pk}/customers/{id}/

Customers of one project.

Body

namestring
—
emailstring (email)
—
external_idstring
Your application's user id, passed to Support.identify().
avatar_urlstring (uri)
—
planstring
Plan reported by your app, e.g. pro.
browserstring
—
operating_systemstring
—
current_pagestring (uri)
—
localestring
—
timezonestring
—
metadataobject
Free-form JSON sent from your app. Shown in the customer panel.
tag_idsstring (uuid)[]
—
first_seen_atstring (date-time)
—
last_seen_atstring (date-time)
—
is_blockedboolean
—

Responses

Update customer

PATCH/projects/{project_pk}/customers/{id}/

Customers of one project.

Body

namestring
—
emailstring (email)
—
external_idstring
Your application's user id, passed to Support.identify().
avatar_urlstring (uri)
—
planstring
Plan reported by your app, e.g. pro.
browserstring
—
operating_systemstring
—
current_pagestring (uri)
—
localestring
—
timezonestring
—
metadataobject
Free-form JSON sent from your app. Shown in the customer panel.
tag_idsstring (uuid)[]
—
first_seen_atstring (date-time)
—
last_seen_atstring (date-time)
—
is_blockedboolean
—

Responses

Delete customer

DELETE/projects/{project_pk}/customers/{id}/

Hard delete, including their tickets. Prefer anonymize to keep ticket history.

Responses

  • 204 — no body · No response body

Merge duplicate customer

POST/projects/{project_pk}/customers/{id}/merge/

Moves the duplicate's tickets, messages, notes and tags onto this customer, then deletes the duplicate. Irreversible.

Body

duplicate_idstring (uuid)required
The customer that will be removed.

Responses

Objects

What comes back, described once each rather than under every endpoint that returns it. Every field here is read-only: these are responses, and what a request accepts is listed with the operation itself.

Attachment

A file on a message. Uploaded as multipart together with the target message id.

idstring (uuid)read-only
—
filestring (uri)| null
The file itself on the way in; a signed link that expires on the way out.
filenamestring
—
content_typestring
—
size_bytesintegerread-only
—
is_inlineboolean
—
content_idstringread-only
—
created_atstring (date-time)read-only
—

Customer

Full customer profile shown in the context panel and detail screen.

idstring (uuid)read-only
—
namestring
—
display_namestringread-only
—
emailstring (email)
—
external_idstring
Your application's user id, passed to Support.identify().
avatar_urlstring (uri)
—
planstring
Plan reported by your app, e.g. pro.
browserstring
—
operating_systemstring
—
current_pagestring (uri)
—
localestring
—
timezonestring
—
metadataobject
Free-form JSON sent from your app. Shown in the customer panel.
tagsTag[]read-only
—
ticket_countintegerread-only
—
open_ticket_countintegerread-only
—
resolved_ticket_countintegerread-only
—
first_seen_atstring (date-time)
—
last_seen_atstring (date-time)
—
is_identity_verifiedbooleanread-only
True when the chat session was signed with your project secret.
is_blockedboolean
—
is_anonymizedbooleanread-only
—
anonymized_atstring (date-time)| nullread-only
—
created_atstring (date-time)read-only
—
updated_atstring (date-time)read-only
—

CustomerList

Row shown in the customer list.

idstring (uuid)read-only
—
namestringread-only
—
display_namestringread-only
—
emailstring (email)read-only
—
external_idstringread-only
Your application's user id, passed to Support.identify().
avatar_urlstring (uri)read-only
—
planstringread-only
Plan reported by your app, e.g. pro.
tagsTag[]read-only
—
ticket_countintegerread-only
—
open_ticket_countintegerread-only
—
first_seen_atstring (date-time)read-only
—
last_seen_atstring (date-time)read-only
—
is_identity_verifiedbooleanread-only
True when the chat session was signed with your project secret.
is_blockedbooleanread-only
—
is_anonymizedbooleanread-only
—
created_atstring (date-time)read-only
—

CustomerMergeResult

idstring (uuid)read-only
—
primarystring (uuid)read-only
—
merged_customer_idstring (uuid)read-only
—
merged_emailstring (email)read-only
—
merged_external_idstringread-only
—
moved_ticket_countintegerread-only
—
performed_byUserSummaryread-only
—
created_atstring (date-time)read-only
—

Message

A message in the conversation: customer message, agent reply, note or system entry.

idstring (uuid)read-only
—
kindstringread-only
One ofcustomer, reply, note, system
sourcestringread-only
The channel a customer message arrived on. Blank for a reply, note or system entry. * `email` - Email * `chat` - Chat * `api` - API * `portal` - PortalOne ofemail, chat, api, portal
body_htmlstringread-only
—
body_textstringread-only
—
author_userUserSummaryread-only
—
author_customerobject| nullread-only
—
attachmentsAttachment[]read-only
—
mentioned_usersUserSummary[]read-only
—
is_internalbooleanread-only
—
delivery_statusstringread-only
One ofnot_applicable, queued, sent, delivered, bounced, failed
delivery_errorstringread-only
—
delivered_atstring (date-time)| nullread-only
—
email_message_idstringread-only
—
from_addressstring (email)read-only
—
to_addressstring (email)read-only
—
metadataobjectread-only
—
created_atstring (date-time)read-only
—

ReplyDestination

Where the next agent reply on a ticket goes, and the address it comes from. A reply always appears in the widget when `in_widget` is set, and is mailed to `customer_email` unless the visitor is reading that widget right now - so `is_visitor_present` is the one field here that changes minute to minute, and the ticket update feed reports it on every answer. `emails_enabled` is the project-wide switch and outranks all of it: with it off nothing is mailed, whatever the other three say.

customer_emailstringread-only
The address a reply is mailed to. Empty for an unidentified visitor.
in_widgetbooleanread-only
The conversation started in the chat widget, where replies are shown.
is_visitor_presentbooleanread-only
The customer has the widget open now, so a reply reaches them there and is not mailed.
emails_enabledbooleanread-only
The project sends email to its customers. False means no reply is mailed at all - on a widget conversation it is still delivered in the chat, on an email ticket it reaches nobody.
from_namestringread-only
—
from_addressstringread-only
The address a reply is sent from.
from_sourcestringread-only
Why the reply comes from that address. `platform_default` means the project has not set up sending. * `project_smtp` - The project's own mail server * `verified_domain` - A domain verified for sending * `platform_default` - Helpwing's shared addressOne ofproject_smtp, verified_domain, platform_default

Tag

idstring (uuid)read-only
—
namestring
—
slugstringread-only
—
colorstring
Hex color, e.g. #64748b.
descriptionstring
—
usage_countintegerread-only
—
created_atstring (date-time)read-only
—

Ticket

Full ticket used by the conversation workspace.

idstring (uuid)read-only
—
referencestringread-only
The conversation's public identifier. Opaque, and the only one a customer ever sees.
subjectstring
—
statusstring
One ofopen, pending, resolved, closed
prioritystring
One oflow, normal, high, urgent
sourcestring
One ofemail, chat, api, portal
customerCustomerListread-only
—
assigneeUserSummaryread-only
—
tagsTag[]read-only
—
inboxstring (uuid)| null
—
is_spamboolean
—
is_mergedbooleanread-only
—
merged_intostring (uuid)| nullread-only
—
viewersobject[]read-only
Other members currently viewing this ticket, for the collision warning.
reply_destinationReplyDestinationread-only
Where a reply written now would be delivered, and the address it would come from.
message_countintegerread-only
—
last_message_previewstringread-only
—
last_message_atstring (date-time)read-only
—
first_response_atstring (date-time)| nullread-only
—
resolved_atstring (date-time)| nullread-only
—
closed_atstring (date-time)| nullread-only
—
external_refstring
Your own identifier, set when creating tickets over the API.
email_thread_idstring
—
metadataobject
—
created_atstring (date-time)read-only
—
updated_atstring (date-time)read-only
—

TicketBulkResult

updatedinteger
—
skippedinteger
—

TicketList

Row shown in the ticket list column of the inbox.

idstring (uuid)read-only
—
referencestringread-only
The conversation's public identifier. Opaque, and the only one a customer ever sees.
subjectstringread-only
—
statusstringread-only
One ofopen, pending, resolved, closed
prioritystringread-only
One oflow, normal, high, urgent
sourcestringread-only
One ofemail, chat, api, portal
customerobjectread-only
—
assigneeUserSummaryread-only
—
tagsTag[]read-only
—
inboxstring (uuid)| nullread-only
—
is_spambooleanread-only
—
is_unreadbooleanread-only
True when the ticket changed since you last read it.
message_countintegerread-only
—
last_message_previewstringread-only
—
last_message_atstring (date-time)read-only
—
created_atstring (date-time)read-only
—

UserSummary

Compact user representation embedded in tickets, notes and members.

idstring (uuid)read-only
—
emailstring (email)read-only
—
full_namestringread-only
Display name shown to teammates.
display_namestringread-only
—
avatar_urlstring (uri)read-only
—