Перейти к содержимому
Helpwing Docs
Start free

API reference

The 26 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.ru/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}/

Subject, priority, spam flag, external reference and metadata. Status, assignee and tags have their own actions; sending them here is a 400.

Body

subjectstringrequired
—
prioritystring
One oflow, normal, high, urgent
is_spamboolean
—
external_refstring
Your own identifier, set when creating tickets over the API.
metadataobject
—

Responses

Update ticket

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

Subject, priority, spam flag, external reference and metadata. Status, assignee and tags have their own actions; sending them here is a 400.

Body

subjectstring
—
prioritystring
One oflow, normal, high, urgent
is_spamboolean
—
external_refstring
Your own identifier, set when creating tickets over the API.
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/

Records a delivery failure reported by the mail provider. Owners, admins and API keys only.

Responses

Send reply by email

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

Emails a reply that was delivered in the chat only (delivery_status: not_applicable). Sent even if the visitor is reading the chat right now. Requires customer email to be enabled on the project and an address on the customer.

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. Owners, admins and API keys only. 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
—