Developers · API reference
Schemas
The objects of the UPPU customer API v1 other than messages and templates, generated from the copy of the OpenAPI document pinned on this site. The endpoints are on the API reference; messages, message content, templates and media are on the message schemas page.
- API version
v1 - OpenAPI
3.1.0 - Generated from
a1fec8942· 19 November 2026
Schemas
Objects used by the endpoints and the webhook event. Fields marked “required” are always present; nullable fields are present with null.
IdTimestampNullableTimestampChannelListChannelChannelForeignAppsChannelHealthChannelCapabilitiesErrorEnvelopeErrorContactLookupRequestContactConsentRequestConsentListConsentConversationListConversationWithInboxStateHandoverRequestReportSummaryReportFeaturesReportPeriodReportScopeReportTotalsReportDurationsReportSlaReportSlaCountsReportSlaCountReportTopicReportTagReportBreakdownsReportRowReportDayListReportDayEventListEventWebhookEndpointListWebhookEndpointWebhookEndpointCreateRequestWebhookEndpointUpdateRequestWebhookEndpointTestRequestWebhookEndpointCheckDeletedWebhookEndpoint
Id
Type string
pattern ^[0-9a-hjkmnp-tv-z]{26}$
Timestamp
Type string
pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
NullableTimestamp
Type string | null
pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
ChannelList
| Field | Type | Description |
|---|---|---|
objectrequired | "list" | |
datarequired | array of Channel | |
next_cursorrequired | string | null |
Channel
| Field | Type | Description |
|---|---|---|
objectrequired | "channel" | |
idrequired | Id | |
typerequired | string |
|
namerequired | string | |
display_phonerequired | string | null | E.164 with a plus sign; null for web channels. |
handlerequired | string | null | How people find the channel; on Telegram the bot's @username, on e-mail the sending address (null until it is set), null on other channel types (added within v1). |
contact_urlrequired | string | null | A link that opens a chat with the channel; on Telegram https://t.me/<bot username>, to which ?start=<parameter> may be appended (1-64 of A-Z a-z 0-9 _ -; it arrives as context.start_parameter). On e-mail mailto:<sending address> (null until it is set). Null on other channel types (added within v1). |
moderequired | string |
|
statusrequired | string |
|
handlingrequired | string | Who answers on the channel. inbox is the team inbox, api your own system, bot UPPU Bot. This is the choice the company owner stored: it stays the same when the company's plan changes. While UPPU Bot is not in the plan, a bot channel runs as a team inbox channel. In a company whose plan has no messaging panel nobody answers in UPPU: inbox and bot channels get no assignment and resolve every idle open conversation after 24 hours.
|
botrequired | object | null | The UPPU Bot that answers on a channel whose handling is bot: its display name, which is also the author.label of its messages. Null on other channels (added within v1). |
sendingrequired | string |
|
sending_reasonrequired | string | null | Why sending is unavailable; the same codes as details.reason of channel_unavailable. team_disabled is retired within v1 and no longer produced: a company's plan never stops the sends of a connected channel (a channel type removed from the plan keeps working); the value stays listed for older clients. A company's Telegram gate likewise stops new connections only, never the sends of a connected bot. E-mail channels (added within v1): email_off (UPPU's e-mail channel is switched off), no_sender (no sending address is set) and sender_unverified (the domain of the sending address is not verified in the panel: its DKIM record was not found).
|
healthrequired | ChannelHealth | null | |
messaging_limitrequired | string | null | Meta's messaging limit tier (WhatsApp only). |
qualityrequired | string | null | Meta's quality rating (WhatsApp only). |
capabilitiesrequired | ChannelCapabilities | |
created_atrequired | Timestamp | |
email | object | E-mail only, present only on e-mail channels (added within v1). inbound_address is the UPPU address the company forwards its support address to (null while UPPU's e-mail channel is switched off); from_address the sending address of the replies; sender_verified whether its domain is verified (its DKIM record found), without which nothing is sent. |
email.inbound_addressrequired | string | null | |
email.from_addressrequired | string | null | |
email.sender_verifiedrequired | boolean | |
foreign_apps | ChannelForeignApps | null | WhatsApp only, present only on WhatsApp channels (added within v1): the Meta apps other than UPPU's that are subscribed to the channel's WhatsApp Business Account, read with the channel checklist (every 15 minutes) from Meta's subscribed_apps list. Customers do not call Meta directly: an app listed here still receives this account's webhooks from Meta and can act on the account outside UPPU. Remove it from the account in Meta Business Settings and revoke its tokens on a date agreed with UPPU: for a number moved to UPPU this is the revocation step, 7 stable days after the move, and until then red is expected. UPPU only reads the list and never changes it. Not part of health. Null until the list has been read completely. |
ChannelForeignApps
| Field | Type | Description |
|---|---|---|
statusrequired | string | red: at least one other app was subscribed at the last read; green: only UPPU's app, read within the last hour; unknown: no other app at the last read, but that read is older than an hour or UPPU's own app was not subscribed either (the channel's health then reports app_not_subscribed); not_applicable: UPPU does not serve the number in live mode (shadow mode, disconnected), so the account may still use other apps.
|
appsrequired | array of object | The other apps at the last read, by Meta's app id; name is the app's name on Meta. |
apps[].idrequired | string | |
apps[].namerequired | string | null | |
checked_atrequired | Timestamp | The last successful read. |
changed_atrequired | NullableTimestamp | When the set of other apps last changed. Not the status: the status also follows the age of the read, UPPU's own subscription and the channel's mode. |
ChannelHealth
| Field | Type | Description |
|---|---|---|
statusrequired | string |
|
reasonsrequired | array of string | Reason codes of the checklist items that are not green. Telegram channels (added within v1) have items 1, 7, 8 and 9 only, with their own codes (for example webhook_elsewhere, webhook_missing, webhook_errors, webhook_backlog, token_rejected, sending_paused, telegram_unreachable); unknown codes are to be accepted. On WhatsApp, item 5 (payment method) is red with funding_missing (Meta shows no payment method), billing_fields_missing (the account's currency or time zone is empty), payment_error_131042 (Meta refused a message for a payment reason in the last 7 days) or payment_error_141006 (Meta reported a payment account problem on a message in the last 7 days, or reports it in the account's health status); on item 4, verification_unreadable (Meta does not show the field) is a grey code added within v1. |
checked_atrequired | NullableTimestamp |
ChannelCapabilities
| Field | Type | Description |
|---|---|---|
content_typesrequired | array of string | |
interactive_typesrequired | array of string | The interactive types the channel sends (added within v1); empty when interactive is not a content type. cta_url (WhatsApp, Messenger) and request_phone (Telegram) were added within v1. |
limitsrequired | object of integer | Per-field limits. Keys ending in _bytes count UTF-8 bytes (Instagram text_body_bytes), keys ending in _utf16 count UTF-16 code units, as JavaScript's String.length does (Telegram text_body_utf16 and caption_utf16); the other keys count characters, or items for counts such as buttons and quick_replies. The values are UPPU's and may change. Where the provider's documentation states a limit, UPPU's is the same or lower, except that Instagram's documentation also asks for a text shorter than 1,000 characters. Where it states none (for example Messenger's text_body, WhatsApp's template parameters and location fields, file names, Instagram's option_id and most Telegram keys), the value is UPPU's choice and the provider may still refuse a value within it. On WhatsApp interactive_body limits the body of a buttons message and list_body that of a list; button_id limits a reply button's id and option_id a list row's. list_body and button_id were added within v1; until then interactive_body and option_id covered both kinds, so a client that validates with them still sends valid messages. Contact cards (added within v1): contact_cards per message, contact_phones and contact_emails per card, contact_field for every text field of a card (UPPU's values; Telegram takes one card with one phone). Template buttons (added within v1, WhatsApp): template_button_url limits the whole address of a URL button once its variable is filled in, template_button_payload a quick reply's payload (UPPU's values). Link buttons (added within v1): cta_display_text limits a cta_url button's text (the providers' 20), cta_url its address (UPPU's value). |
window_hoursrequired | integer | null | |
phone_addressingrequired | boolean | |
reaction_emojisrequired | array of string | null | The only emojis a reaction may carry (Instagram the heart; Telegram its fixed ReactionTypeEmoji list, matched without the variation selector U+FE0F); null when any single emoji is accepted or the channel sends no reactions (added within v1). |
delivery_statusesrequired | array of string | The statuses the channel reports after queued and accepted (added within v1): WhatsApp sent, delivered and read; Messenger delivered and read; Instagram read; Telegram, web chat and e-mail sent. Do not wait for a status the channel never reports.
|
typing_indicatorrequired | boolean | Whether |
ErrorEnvelope
| Field | Type | Description |
|---|---|---|
errorrequired | Error |
Error
| Field | Type | Description |
|---|---|---|
typerequired | string |
|
coderequired | string |
|
statusrequired | integer | |
retryablerequired | boolean | |
messagerequired | string | Follows Accept-Language (tr by default, en). |
request_idrequired | string | max length |
doc_urlrequired | string | null | |
detailsrequired | object | For example resource (not_found; api_disabled: team, api_key or channel), reason (api_disabled with resource team: not_in_plan, the company's plan does not include the API), required (insufficient_scope), fields (validation_failed: [{field, code, message}]). Added within v1: handling (handling_not_supported: the channel's handling) and reason (handling_not_supported: not_in_plan, the company's plan has no messaging panel; not_held and not_handed_over: conversation_resolved; bot_not_ready: bot_unavailable, bot_busy or reply_first; not_inbound: no_inbound_message for a typing indicator on WhatsApp), scope (rate_limited: conversation, the per-conversation limit of typing indicators, with limit and period_seconds). Added within v1 too: resource, max and used (plan_limit_reached: webhook_endpoint, the limit and the endpoints the company has) and reason (not_found with resource media_link: invalid or expired). Added within v1 with template management and reports: resource reports with reason not_in_plan (api_disabled: the plan has no messaging panel, reports are part of it), resource member and group (not_found), reason templates_per_hour, concurrent_writes and provider_rate_limited (rate_limited; provider_rate_limited: Meta's own rate limit, with Meta's code in provider_error), reason credentials also when Meta refused the access token (channel_unavailable) and reason unreachable or unconfirmed (provider_unavailable: Meta could not be reached, or did not confirm the change because it did not answer in time or had a temporary error, so the change may have been made). |
provider_errorrequired | ProviderError | null |
ContactLookupRequest
The channel and exactly one of phone (E.164, WhatsApp channels) or identity. Added within v1: phone also works on Telegram channels (a number the person shared from their own account).
| Field | Type | Description |
|---|---|---|
channel_idrequired | Id | |
phone | string | pattern |
identity | object | |
identity.typerequired | string |
|
identity.valuerequired | string | max length |
Contact
| Field | Type | Description |
|---|---|---|
objectrequired | "contact" | |
idrequired | Id | |
display_namerequired | string | null | The name shown in the inbox: the name an agent wrote, the WhatsApp profile name, on Messenger and Instagram the name UPPU reads from Meta's profile endpoint after the contact's first message (Instagram falls back to @username), or on Telegram the name every update carries (first and last name, otherwise @username; present from the first message). An agent-edited name is never overwritten. Null until a name is known. |
blockedrequired | boolean | |
merged_intorequired | string | null | Reserved; always null. |
identitiesrequired | array of object | Identities on the key's channels; superseded identities have current false. Added within v1: on e-mail channels type email is the address the person wrote from (their Reply-To when they gave one), in lower case. Accept unknown types. |
identities[].channel_idrequired | Id | |
identities[].typerequired | string | |
identities[].valuerequired | string | |
identities[].currentrequired | boolean | |
service_windowsrequired | array of object | The 24-hour reply window per WhatsApp, Messenger or Instagram channel, counted from Meta's timestamp of the person's last message (never later than when UPPU received it); on Messenger and Instagram also of their last reaction (added within v1). |
service_windows[].channel_idrequired | Id | |
service_windows[].openrequired | boolean | |
service_windows[].closes_atrequired | NullableTimestamp | |
consentsrequired | array of object | The current consent per channel type and purpose. |
consents[].channel_typerequired | string | |
consents[].purposerequired | string |
|
consents[].staterequired | string |
|
consents[].recorded_atrequired | NullableTimestamp | |
created_atrequired | NullableTimestamp | |
notesrequired | string | null | The team's notes about the person, written in the inbox contact panel (plain text, at most 5000 characters; null without notes). Not the internal notes of a conversation. Added within v1. |
attributesrequired | object of string | number | The company's contact fields that have a value for this person, by field name (the name the owner or an admin gave the field in the panel). A text field is a string, a number field a number, a date field a "YYYY-MM-DD" string and a list field one of its options. An empty object when no field has a value. The team fills them in the inbox contact panel. Added within v1. |
languagerequired | string | null | The person's language as an ISO 639-1 code (two lower-case letters, such as tr, en or ar), or null when it is not known. UPPU takes it from a hint of the channel while no language is known (the language Telegram reports, the browser language of the web chat), from the language of the person's messages, or from the team's choice in the inbox contact panel, which nothing else replaces. The contact keeps only the code, never the raw language tag. UPPU switches the feature on per environment; until then it stays null. Read only in v1. Added within v1. pattern |
ConsentRequest
A consent record to add (POST /consents): the fields of an inline consent plus the channel and the person.
| Field | Type | Description |
|---|---|---|
channel_idrequired | Id | |
torequired | Recipient | |
purposerequired | string |
|
staterequired | string |
|
source_textrequired | string | The exact text the person agreed to (or the withdrawal they asked for). max length |
source_refrequired | string | Your reference to the evidence (no personal data), for example web-form:checkout:7781. max length |
collected_at | string (date-time) | When the person gave or withdrew the consent; now if left out, never in the future. |
ConsentList
| Field | Type | Description |
|---|---|---|
objectrequired | "list" | |
datarequired | array of Consent | |
next_cursorrequired | string | null |
Consent
A record of the consent ledger; records are only added, never changed.
| Field | Type | Description |
|---|---|---|
objectrequired | "consent" | |
idrequired | Id | |
contact_idrequired | Id | |
channel_typerequired | string | |
purposerequired | string |
|
staterequired | string |
|
sourcerequired | string | api (recorded with an API key: |
source_textrequired | string | null | The exact text the person agreed to; null for automatic withdrawals and for withdrawals recorded in the panel or imported without a note. |
source_refrequired | string | null | Your reference to the evidence; null for automatic withdrawals and for imported rows without a reference. For agent_recorded it is how the person told the company (conversation, phone_call, written, in_person or other), followed by ":" and the reference the panel user gave, if any. |
collected_atrequired | Timestamp | When the person gave or withdrew the consent. |
recorded_atrequired | Timestamp | When UPPU recorded it. |
api_key_prefixrequired | string | null | The prefix of the API key that recorded it; null otherwise. |
ConversationList
| Field | Type | Description |
|---|---|---|
objectrequired | "list" | |
datarequired | array of ConversationWithInboxState | |
next_cursorrequired | string | null |
ConversationWithInboxState
A conversation as the REST endpoints return it (added within v1): the fields of Conversation; webhook bodies (conversation.updated) carry Conversation. Ignore unknown fields.
| Field | Type | Description |
|---|---|---|
objectrequired | "conversation" | |
idrequired | Id | |
channel_idrequired | Id | |
contact_idrequired | Id | |
statusrequired | string |
|
handlingrequired | string | The channel's stored handling (inbox the team inbox, api your own system, bot UPPU Bot), also while a module of the company's plan is off (see the channel's handling); accept unknown values.
|
assignedrequired | boolean | Whether a team member is assigned; the assignee is never shown. |
handed_over_atrequired | NullableTimestamp | On api and bot channels: null while the automation (your system or UPPU Bot) holds the conversation, otherwise when it was handed over to the team. On bot channels UPPU Bot hands over by itself (a handover step of its flow, a request for a person, an error), a team member's reply, claim or assignment in the inbox takes the conversation over, and returning it to the bot in the inbox sets it back to null. Conversations that are open when a channel moves to UPPU Bot or away from it are handed over to the team. inbox channels ignore it: the team holds their conversations. In a company whose plan has no messaging panel, bot channels ignore it too (see the channel's handling). Your system hands over and releases with |
held_byrequired | string | Who holds the conversation (added within v1): api (your system, on an api channel), bot (UPPU Bot, on a bot channel) or team (handed over, and every conversation of an inbox channel). It follows the channel's stored handling and handed_over_at, like handling; on a resolved conversation it names who held it last (a conversation reopened by the person's message stays with them). When an owner changes the channel's handling in the panel, the channel's open conversations change hands without a conversation.updated event: moving an api channel to UPPU Bot or to the team inbox gives your system's open conversations to the team, and moving an inbox channel to api gives you its open conversations that were not handed over. Only removing UPPU Bot from a channel sends handed_over (bot_detached) for each conversation the bot held. The channel (
|
handover_reasonrequired | string | null | Why the conversation was last handed over to the team (added within v1); null while the automation holds it, and when the handover has no recorded reason (open conversations stamped when their channel moved to UPPU Bot, or when UPPU Bot came back to the company's plan; the reason of an earlier handover that was released or returned is never carried over). api is your own handover (
|
opened_atrequired | Timestamp | When the conversation was opened; a reopened conversation keeps it. |
resolved_atrequired | NullableTimestamp | When the conversation was resolved; null while it is open. |
last_inbound_atrequired | NullableTimestamp | The provider's timestamp of the person's last message in this conversation (Meta's; on Telegram the message's date; the receive time when the provider sent none, for example a Telegram button tap or a web chat message), never later than when UPPU received it; null if the person never wrote in it, for example a conversation opened by your template. On Messenger and Instagram the person's reaction counts as a message here, since it opens the reply window (added within v1). |
last_message_atrequired | Timestamp | The last activity (inbound, outbound or system message; UPPU's automatic privacy notice on WhatsApp, Messenger and Instagram leaves it unchanged, the time stays that of the contact's message); api and bot channels resolve the idle conversations the automation holds from it. In a company whose plan has no messaging panel, inbox and bot channels resolve every idle open conversation from it, after the same 24 hours (see the channel's handling). |
service_windowrequired | object | null | The contact's current 24-hour reply window on the conversation's channel, as in message.received (counted from the person's latest message on the channel, in any conversation, or on Messenger and Instagram their latest reaction); null on web chat, Telegram and e-mail, which have no reply window. |
HandoverRequest
The optional body of POST /conversations/{id}/handover (added within v1). Both fields appear only in the team inbox, next to the handover; the API and the webhooks never return them.
| Field | Type | Description |
|---|---|---|
reason | string | A short code of your own for why you hand the conversation over, for example customer_request. No personal data. pattern |
note | string | A note for the team (line breaks allowed, no other control characters). max length |
ReportSummary
The report of a period (GET /reports/summary, added within v1): the nightly counters of the panel's Reports page. Counts only. A section the report's tier does not include is null.
| Field | Type | Description |
|---|---|---|
objectrequired | "report_summary" | |
tierrequired | string | The report's tier (basic or full; every company has full until the plan sets it).
|
featuresrequired | ReportFeatures | |
periodrequired | ReportPeriod | |
scoperequired | ReportScope | |
totalsrequired | ReportTotals | |
first_responserequired | ReportDurations | |
resolutionrequired | ReportDurations | |
slarequired | ReportSla | null | response targets met and missed (counted from the targets' moments); null without the response targets feature. |
topicsrequired | array of ReportTopic | null | The topics of new conversations, most first; null without the topics feature. |
tagsrequired | array of ReportTag | null | The other tags of new conversations, most first (a deleted tag has no name); null without the topics feature. |
untaggedrequired | integer | null | New conversations without a tag; null without the topics feature. |
breakdownsrequired | ReportBreakdowns | null | Per channel, agent and group, only for the whole company (scope all); null otherwise. The totals and the agent and group rows count every channel of the company, also the channels UPPU stopped for the API. |
updated_atrequired | NullableTimestamp | When the counters were last written. |
ReportFeatures
The sections of the report's tier.
| Field | Type | Description |
|---|---|---|
volumerequired | boolean | |
timesrequired | boolean | |
channelsrequired | boolean | |
membersrequired | boolean | |
groupsrequired | boolean | |
slarequired | boolean | |
topicsrequired | boolean |
ReportPeriod
| Field | Type | Description |
|---|---|---|
fromrequired | string | pattern |
torequired | string | The last day; never after the last counted day. pattern |
daysrequired | integer | min |
presetrequired | integer | null | 7, 30 or 90 for the days parameter (and its default); null for from and to. |
timezonerequired | string | The company's time zone; days are calendar days there. |
counted_throughrequired | string | null | The last day the nightly count finished; null before the first count. pattern |
pendingrequired | boolean | True while yesterday is not counted yet (the period ends earlier). |
ReportScope
| Field | Type | Description |
|---|---|---|
typerequired | string |
|
idrequired | Id | null | The channel's, agent's or group's id; null for the whole company. |
namerequired | string | null |
ReportTotals
The counts of the period. opened: conversations the contacts opened; team_opened: those that reached the team (on a channel your system or UPPU Bot answers, at the handover); unanswered: of these, without the team's first response on that day; replies: the team's messages; resolved and reopened: every resolve and reopen; open_at_end and open_unassigned_at_end: the team's open conversations at the end of the period's last day; tagged: new conversations with a tag (null without the topics feature).
| Field | Type | Description |
|---|---|---|
openedrequired | integer | min |
team_openedrequired | integer | min |
unansweredrequired | integer | min |
unanswered_sharerequired | integer | null | unanswered of team_opened in percent; null when team_opened is 0. |
repliesrequired | integer | min |
resolvedrequired | integer | min |
reopenedrequired | integer | min |
open_at_endrequired | integer | min |
open_unassigned_at_endrequired | integer | min |
taggedrequired | integer | null |
ReportDurations
First response times (from reaching the team to the team's first response) or resolution times (from the start of the cycle to the resolve, without the time the conversation waited). buckets counts the samples per bucket: at most 1m, 5m, 15m, 30m, 1h, 4h, 8h, 24h, 72h, or over for first responses; 15m, 1h, 4h, 8h, 24h, 72h, 7d, or over for resolutions. median and p90 are the buckets in which half and nine tenths of the samples fall (null without samples); average_seconds is seconds divided by count.
| Field | Type | Description |
|---|---|---|
countrequired | integer | min |
secondsrequired | integer | min |
average_secondsrequired | integer | null | |
medianrequired | string | null | |
p90required | string | null | |
bucketsrequired | object of integer |
ReportSla
| Field | Type | Description |
|---|---|---|
targets_setrequired | boolean | Whether the company has response targets today. |
first_responserequired | ReportSlaCount | |
resolutionrequired | ReportSlaCount |
ReportSlaCounts
| Field | Type | Description |
|---|---|---|
first_responserequired | ReportSlaCount | |
resolutionrequired | ReportSlaCount |
ReportSlaCount
| Field | Type | Description |
|---|---|---|
metrequired | integer | min |
missedrequired | integer | min |
sharerequired | integer | null | met of met and missed in percent; null when both are 0. |
ReportTopic
| Field | Type | Description |
|---|---|---|
idrequired | Id | |
namerequired | string | |
countrequired | integer | min |
ReportTag
| Field | Type | Description |
|---|---|---|
idrequired | Id | |
namerequired | string | null | |
deletedrequired | boolean | |
countrequired | integer | min |
ReportBreakdowns
| Field | Type | Description |
|---|---|---|
channelsrequired | array of ReportRow | The channels the key can see by id, name and type; deleted channels are one row with deleted true and no name, and the channels UPPU stopped for the API are one last row with hidden true and no id, name or type. |
membersrequired | array of ReportRow | null | The agents (members who take conversations, and current members with counts) by id and name; the counts of people who are no longer members are one row with former true and no name. null without the members feature. |
groupsrequired | array of ReportRow | null | The groups; deleted groups are one row with deleted true and no name. null without the groups feature. |
ReportRow
| Field | Type | Description |
|---|---|---|
idrequired | Id | null | The channel's, agent's or group's id; null for the row of deleted channels or groups, of former members and of channels the key cannot see. |
namerequired | string | null | |
typerequired | string | null | The channel's type (channels only; null otherwise). |
deletedrequired | boolean | |
formerrequired | boolean | |
hiddenrequired | boolean | True only for the one channel row that holds the counts of the channels the key cannot see (channels UPPU stopped for the API); its id, name and type are null. Always false for agents and groups. |
totalsrequired | ReportTotals | |
first_responserequired | ReportDurations | |
resolutionrequired | ReportDurations | |
slarequired | ReportSlaCounts | null |
ReportDayList
| Field | Type | Description |
|---|---|---|
objectrequired | "list" | |
datarequired | array of ReportDay | |
next_cursorrequired | string | null |
ReportDay
The counts of one day (GET /reports/daily). answered and unanswered split team_opened by the team's first response on the day; open and open_unassigned are the team's open conversations at the end of the day.
| Field | Type | Description |
|---|---|---|
objectrequired | "report_day" | |
dayrequired | string | pattern |
countedrequired | boolean | Whether the nightly count finished the day (zeros of a day not counted are unknown). |
openedrequired | integer | min |
team_openedrequired | integer | min |
answeredrequired | integer | min |
unansweredrequired | integer | min |
repliesrequired | integer | min |
resolvedrequired | integer | min |
reopenedrequired | integer | min |
openrequired | integer | min |
open_unassignedrequired | integer | min |
taggedrequired | integer | null | |
first_responserequired | ReportDurations | |
resolutionrequired | ReportDurations | |
slarequired | ReportSlaCounts | null |
EventList
| Field | Type | Description |
|---|---|---|
objectrequired | "list" | |
datarequired | array of Event | |
next_cursorrequired | string | null | The id of the last event of this page when more events follow; pass it as after. |
Event
A webhook event; data reuses the REST resources (message, channel ...). Ignore unknown fields and types.
| Field | Type | Description |
|---|---|---|
idrequired | Id | |
objectrequired | "event" | |
typerequired | string |
|
api_versionrequired | "v1" | |
created_atrequired | Timestamp | |
team_idrequired | Id | |
channelrequired | object | null | |
testrequired | boolean | True only for test events (the webhook page's and the API's test event and probe, and the optional weekly test event). |
datarequired | object |
WebhookEndpointList
| Field | Type | Description |
|---|---|---|
objectrequired | "list" | |
datarequired | array of WebhookEndpoint | |
next_cursorrequired | string | null |
WebhookEndpoint
A webhook endpoint of the company, as the panel's Webhooks page shows it. url is masked (scheme, host, the port when it is not 443, and /...): the full address is never shown. secret is the signing secret, only in the answer that creates the endpoint and in the answer of a rotation; null everywhere else. Accept unknown event types, states and reasons.
| Field | Type | Description |
|---|---|---|
objectrequired | "webhook_endpoint" | |
idrequired | Id | |
urlrequired | string | |
eventsrequired | array of string | The subscribed event types (webhook.test always goes and is not listed). |
channel_idrequired | Id | null | The channel filter; null for every channel. |
orderingrequired | string |
|
max_in_flightrequired | integer | |
api_versionrequired | string | |
staterequired | string | pending_verification: new or with a new address, gets no events until it is verified and activated. active. failing: 20 failures in a row, one attempt a minute. suspended: failing for 72 hours or answered 410, events are held for at most 7 days. disabled: turned off.
|
consecutive_failuresrequired | integer | |
failing_sincerequired | NullableTimestamp | |
suspended_atrequired | NullableTimestamp | |
suspended_reasonrequired | string | null | gone (the endpoint answered 410) or failing (72 hours). |
disabled_atrequired | NullableTimestamp | |
last_success_atrequired | NullableTimestamp | |
last_failure_atrequired | NullableTimestamp | |
verificationrequired | object | Whether a test event and the wrong-signature probe passed within the last hour, and their last HTTP status. |
verification.test_passedrequired | boolean | |
verification.probe_passedrequired | boolean | |
verification.probe_requiredrequired | boolean | Activation needs the probe too (a new endpoint or a new address). |
verification.last_test_statusrequired | integer | null | |
verification.last_probe_statusrequired | integer | null | |
secret_rotating_untilrequired | string | null | Until when the secret replaced by the last rotation still signs; null when none does. pattern |
weekly_testrequired | object | The optional weekly test event: UPPU sends webhook.test once a week to an active or failing endpoint that opted in. A failure only sets failed_at (a warning); the endpoint is never suspended for it. A passing weekly test or test event, turning the weekly test off and a new url clear failed_at. last_status is null when no HTTP answer came (for example a refused address or a timeout). |
weekly_test.enabledrequired | boolean | |
weekly_test.last_sent_atrequired | NullableTimestamp | |
weekly_test.last_statusrequired | integer | null | |
weekly_test.failed_atrequired | NullableTimestamp | |
secretrequired | string | null | whsec_ and 44 base64 characters; only in the answer that creates the endpoint and in the answer of a rotation. pattern |
created_atrequired | Timestamp |
WebhookEndpointCreateRequest
| Field | Type | Description |
|---|---|---|
urlrequired | string | Your https address on port 443, at most 2048 characters. max length |
events | array of string | At least one type; left out, the types that are on by default. template.category_changed, channel.quality_changed and template.category_change_closed (added within v1) only while account protection is on for it; otherwise 422 validation_failed.
|
channel_id | Id | null | Only the events of this channel; null for every channel. |
ordering | string | default
|
max_in_flight | integer | min |
weekly_test | boolean | Send a test event every week (a failure is only a warning). default |
WebhookEndpointUpdateRequest
Only the fields you send change.
| Field | Type | Description |
|---|---|---|
url | string | A new address sends the endpoint back to verification. max length |
events | array of string |
|
channel_id | Id | null | |
ordering | string |
|
max_in_flight | integer | min |
weekly_test | boolean |
WebhookEndpointTestRequest
| Field | Type | Description |
|---|---|---|
type | string | The event type of the sample (webhook.test if left out).
|
WebhookEndpointCheck
The result of a test event or of the wrong-signature probe.
| Field | Type | Description |
|---|---|---|
objectrequired | "webhook_endpoint_check" | |
endpoint_idrequired | Id | |
kindrequired | string |
|
typerequired | string | |
passedrequired | boolean | test: your server answered 2xx. probe: your server refused the wrong signature (any answer other than 2xx). |
statusrequired | integer | null | The HTTP status; null when no answer came (for example a refused address or a timeout). |
latency_msrequired | integer | |
response_excerptrequired | string | null | The first characters of your server's answer. |
errorrequired | string | null | Why the request failed, the address masked; null when your server answered. |
checked_atrequired | Timestamp |
DeletedWebhookEndpoint
| Field | Type | Description |
|---|---|---|
objectrequired | "webhook_endpoint" | |
idrequired | Id | |
deletedrequired | true |
Generated from openapi.json (commit a1fec8942, 19 November 2026) · Live OpenAPI document