Skip to content

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.

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

ChannelList: Fields
FieldTypeDescription
objectrequired"list"
datarequiredarray of Channel
next_cursorrequiredstring | null

Channel

Channel: Fields
FieldTypeDescription
objectrequired"channel"
idrequiredId
typerequiredstring
  • whatsapp
  • instagram
  • messenger
  • telegram
  • web
  • email
namerequiredstring
display_phonerequiredstring | null

E.164 with a plus sign; null for web channels.

handlerequiredstring | 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_urlrequiredstring | 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).

moderequiredstring
  • live
  • shadow
statusrequiredstring
  • pending
  • active
  • paused
  • disconnected
handlingrequiredstring

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.

  • inbox
  • api
  • botComing soon
botrequiredobject | 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).

sendingrequiredstring
  • active
  • paused
  • unavailable
sending_reasonrequiredstring | 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).

  • shadow_mode
  • meta_off
  • telegram_off
  • team_disabled
  • not_linked
  • not_active
  • no_token
  • not_supported
  • email_off
  • no_sender
  • sender_unverified
  • null
healthrequiredChannelHealth | null
messaging_limitrequiredstring | null

Meta's messaging limit tier (WhatsApp only).

qualityrequiredstring | null

Meta's quality rating (WhatsApp only).

capabilitiesrequiredChannelCapabilities
created_atrequiredTimestamp
emailobject

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_addressrequiredstring | null
email.from_addressrequiredstring | null
email.sender_verifiedrequiredboolean
foreign_appsChannelForeignApps | 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

ChannelForeignApps: Fields
FieldTypeDescription
statusrequiredstring

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.

  • green
  • red
  • unknown
  • not_applicable
appsrequiredarray of object

The other apps at the last read, by Meta's app id; name is the app's name on Meta.

apps[].idrequiredstring
apps[].namerequiredstring | null
checked_atrequiredTimestamp

The last successful read.

changed_atrequiredNullableTimestamp

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

ChannelHealth: Fields
FieldTypeDescription
statusrequiredstring
  • green
  • amber
  • red
  • unknown
reasonsrequiredarray 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_atrequiredNullableTimestamp

ChannelCapabilities

ChannelCapabilities: Fields
FieldTypeDescription
content_typesrequiredarray of string
interactive_typesrequiredarray 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.

limitsrequiredobject 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_hoursrequiredinteger | null
phone_addressingrequiredboolean
reaction_emojisrequiredarray 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_statusesrequiredarray 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.

  • sent
  • delivered
  • read
typing_indicatorrequiredboolean

Whether POST /conversations/{id}/typing works on the channel (added within v1): WhatsApp, Messenger and Telegram.

ErrorEnvelope

ErrorEnvelope: Fields
FieldTypeDescription
errorrequiredError

Error

Error: Fields
FieldTypeDescription
typerequiredstring
  • authentication
  • permission
  • invalid_request
  • conflict
  • policy
  • rate_limit
  • server
coderequiredstring
  • invalid_json
  • invalid_request
  • idempotency_key_required
  • idempotency_key_invalid
  • missing_api_key
  • invalid_api_key
  • wrong_environment
  • insufficient_scope
  • channel_not_allowed
  • ip_not_allowed
  • browser_request_refused
  • api_disabled
  • tenant_read_only
  • service_stopped
  • shadow_mode
  • not_found
  • method_not_allowed
  • idempotency_key_reused
  • channel_paused
  • channel_unavailable
  • tenant_not_ready
  • plan_limit_reached
  • media_not_ready
  • not_held
  • not_handed_over
  • bot_not_ready
  • media_expired
  • payload_too_large
  • media_too_large
  • unsupported_media_type
  • validation_failed
  • window_closed
  • consent_required
  • consent_withdrawn
  • contact_blocked
  • recipient_unreachable
  • template_not_found
  • template_not_approved
  • template_parameters_invalid
  • template_category_not_allowed
  • recipient_invalid
  • recipient_not_found
  • reply_target_invalid
  • content_not_supported_on_channel
  • not_inbound
  • media_unavailable
  • handling_not_supported
  • rate_limited
  • channel_backlog
  • internal_error
  • service_unavailable
  • provider_unavailable
statusrequiredinteger
retryablerequiredboolean
messagerequiredstring

Follows Accept-Language (tr by default, en).

request_idrequiredstring

max length 64

doc_urlrequiredstring | null
detailsrequiredobject

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_errorrequiredProviderError | 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).

ContactLookupRequest: Fields
FieldTypeDescription
channel_idrequiredId
phonestring

pattern ^\+[1-9][0-9]{4,19}$

identityobject
identity.typerequiredstring
  • bsuid
  • psid
  • igsid
  • web_visitor
  • telegram
  • email
identity.valuerequiredstring

max length 255

Contact

Contact: Fields
FieldTypeDescription
objectrequired"contact"
idrequiredId
display_namerequiredstring | 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.

blockedrequiredboolean
merged_intorequiredstring | null

Reserved; always null.

identitiesrequiredarray 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_idrequiredId
identities[].typerequiredstring
identities[].valuerequiredstring
identities[].currentrequiredboolean
service_windowsrequiredarray 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_idrequiredId
service_windows[].openrequiredboolean
service_windows[].closes_atrequiredNullableTimestamp
consentsrequiredarray of object

The current consent per channel type and purpose.

consents[].channel_typerequiredstring
consents[].purposerequiredstring
  • marketing
  • utility
consents[].staterequiredstring
  • granted
  • withdrawn
consents[].recorded_atrequiredNullableTimestamp
created_atrequiredNullableTimestamp
notesrequiredstring | 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.

attributesrequiredobject 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.

languagerequiredstring | 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 ^[a-z]{2}$

ConsentRequest

A consent record to add (POST /consents): the fields of an inline consent plus the channel and the person.

ConsentRequest: Fields
FieldTypeDescription
channel_idrequiredId
torequiredRecipient
purposerequiredstring
  • marketing
  • utility
staterequiredstring
  • granted
  • withdrawn
source_textrequiredstring

The exact text the person agreed to (or the withdrawal they asked for).

max length 2000

source_refrequiredstring

Your reference to the evidence (no personal data), for example web-form:checkout:7781.

max length 191

collected_atstring (date-time)

When the person gave or withdrew the consent; now if left out, never in the future.

ConsentList

ConsentList: Fields
FieldTypeDescription
objectrequired"list"
datarequiredarray of Consent
next_cursorrequiredstring | null

ConversationList

ConversationList: Fields
FieldTypeDescription
objectrequired"list"
datarequiredarray of ConversationWithInboxState
next_cursorrequiredstring | 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.

ConversationWithInboxState: Fields
FieldTypeDescription
objectrequired"conversation"
idrequiredId
channel_idrequiredId
contact_idrequiredId
statusrequiredstring
  • open
  • resolved
handlingrequiredstring

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.

  • inbox
  • api
  • botComing soon
assignedrequiredboolean

Whether a team member is assigned; the assignee is never shown.

handed_over_atrequiredNullableTimestamp

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 POST /conversations/{id}/handover and /release (added within v1).

held_byrequiredstring

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 (GET /channels) and the conversation.handling of message.received show the new handling; re-read the channel's open conversations (GET /conversations?channel_id=…&status=open) when it changes. Accept unknown values.

  • api
  • botComing soon
  • team
handover_reasonrequiredstring | 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 (POST /conversations/{id}/handover); the others are UPPU Bot's, for example flow (a handover step of its flow), keyword (the person asked for a person), agent_takeover (a team member replied, claimed or assigned it), bot_detached (the bot was removed from the channel), external_reply (someone replied outside UPPU), staff_initiated (the person answered a template of the team) and schedule (a new conversation came outside the bot's schedule on the channel). Accept unknown values.

  • flow
  • keyword
  • low_confidence
  • max_attempts
  • llm_unavailable
  • llm_busy
  • action_error
  • action_unknown
  • identity_unverified
  • window_closed
  • stale
  • policy_refused
  • unsupported_content
  • budget_exceeded
  • loop_detected
  • turn_failed
  • step_budget
  • pipeline_stalled
  • send_failed
  • bot_unavailable
  • bot_detached
  • agent_takeover
  • external_reply
  • staff_initiated
  • api
  • schedule
  • null
opened_atrequiredTimestamp

When the conversation was opened; a reopened conversation keeps it.

resolved_atrequiredNullableTimestamp

When the conversation was resolved; null while it is open.

last_inbound_atrequiredNullableTimestamp

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_atrequiredTimestamp

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_windowrequiredobject | 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.

HandoverRequest: Fields
FieldTypeDescription
reasonstring

A short code of your own for why you hand the conversation over, for example customer_request. No personal data.

pattern ^[A-Za-z0-9._:-]+$ · max length 64

notestring

A note for the team (line breaks allowed, no other control characters).

max length 1000

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.

ReportSummary: Fields
FieldTypeDescription
objectrequired"report_summary"
tierrequiredstring

The report's tier (basic or full; every company has full until the plan sets it).

  • basic
  • full
featuresrequiredReportFeatures
periodrequiredReportPeriod
scoperequiredReportScope
totalsrequiredReportTotals
first_responserequiredReportDurations
resolutionrequiredReportDurations
slarequiredReportSla | null

response targets met and missed (counted from the targets' moments); null without the response targets feature.

topicsrequiredarray of ReportTopic | null

The topics of new conversations, most first; null without the topics feature.

tagsrequiredarray of ReportTag | null

The other tags of new conversations, most first (a deleted tag has no name); null without the topics feature.

untaggedrequiredinteger | null

New conversations without a tag; null without the topics feature.

breakdownsrequiredReportBreakdowns | 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_atrequiredNullableTimestamp

When the counters were last written.

ReportFeatures

The sections of the report's tier.

ReportFeatures: Fields
FieldTypeDescription
volumerequiredboolean
timesrequiredboolean
channelsrequiredboolean
membersrequiredboolean
groupsrequiredboolean
slarequiredboolean
topicsrequiredboolean

ReportPeriod

ReportPeriod: Fields
FieldTypeDescription
fromrequiredstring

pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

torequiredstring

The last day; never after the last counted day.

pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

daysrequiredinteger

min 1 · max 90

presetrequiredinteger | null

7, 30 or 90 for the days parameter (and its default); null for from and to.

timezonerequiredstring

The company's time zone; days are calendar days there.

counted_throughrequiredstring | null

The last day the nightly count finished; null before the first count.

pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

pendingrequiredboolean

True while yesterday is not counted yet (the period ends earlier).

ReportScope

ReportScope: Fields
FieldTypeDescription
typerequiredstring
  • all
  • channel
  • member
  • group
idrequiredId | null

The channel's, agent's or group's id; null for the whole company.

namerequiredstring | 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).

ReportTotals: Fields
FieldTypeDescription
openedrequiredinteger

min 0

team_openedrequiredinteger

min 0

unansweredrequiredinteger

min 0

unanswered_sharerequiredinteger | null

unanswered of team_opened in percent; null when team_opened is 0.

repliesrequiredinteger

min 0

resolvedrequiredinteger

min 0

reopenedrequiredinteger

min 0

open_at_endrequiredinteger

min 0

open_unassigned_at_endrequiredinteger

min 0

taggedrequiredinteger | 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.

ReportDurations: Fields
FieldTypeDescription
countrequiredinteger

min 0

secondsrequiredinteger

min 0

average_secondsrequiredinteger | null
medianrequiredstring | null
p90requiredstring | null
bucketsrequiredobject of integer

ReportSla

ReportSla: Fields
FieldTypeDescription
targets_setrequiredboolean

Whether the company has response targets today.

first_responserequiredReportSlaCount
resolutionrequiredReportSlaCount

ReportSlaCounts

ReportSlaCounts: Fields
FieldTypeDescription
first_responserequiredReportSlaCount
resolutionrequiredReportSlaCount

ReportSlaCount

ReportSlaCount: Fields
FieldTypeDescription
metrequiredinteger

min 0

missedrequiredinteger

min 0

sharerequiredinteger | null

met of met and missed in percent; null when both are 0.

ReportTopic

ReportTopic: Fields
FieldTypeDescription
idrequiredId
namerequiredstring
countrequiredinteger

min 0

ReportTag

ReportTag: Fields
FieldTypeDescription
idrequiredId
namerequiredstring | null
deletedrequiredboolean
countrequiredinteger

min 0

ReportBreakdowns

ReportBreakdowns: Fields
FieldTypeDescription
channelsrequiredarray 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.

membersrequiredarray 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.

groupsrequiredarray of ReportRow | null

The groups; deleted groups are one row with deleted true and no name. null without the groups feature.

ReportRow

ReportRow: Fields
FieldTypeDescription
idrequiredId | 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.

namerequiredstring | null
typerequiredstring | null

The channel's type (channels only; null otherwise).

deletedrequiredboolean
formerrequiredboolean
hiddenrequiredboolean

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.

totalsrequiredReportTotals
first_responserequiredReportDurations
resolutionrequiredReportDurations
slarequiredReportSlaCounts | null

ReportDayList

ReportDayList: Fields
FieldTypeDescription
objectrequired"list"
datarequiredarray of ReportDay
next_cursorrequiredstring | 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.

ReportDay: Fields
FieldTypeDescription
objectrequired"report_day"
dayrequiredstring

pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

countedrequiredboolean

Whether the nightly count finished the day (zeros of a day not counted are unknown).

openedrequiredinteger

min 0

team_openedrequiredinteger

min 0

answeredrequiredinteger

min 0

unansweredrequiredinteger

min 0

repliesrequiredinteger

min 0

resolvedrequiredinteger

min 0

reopenedrequiredinteger

min 0

openrequiredinteger

min 0

open_unassignedrequiredinteger

min 0

taggedrequiredinteger | null
first_responserequiredReportDurations
resolutionrequiredReportDurations
slarequiredReportSlaCounts | null

EventList

EventList: Fields
FieldTypeDescription
objectrequired"list"
datarequiredarray of Event
next_cursorrequiredstring | 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.

Event: Fields
FieldTypeDescription
idrequiredId
objectrequired"event"
typerequiredstring
  • message.received
  • message.status
  • message.created
  • contact.identity_changed
  • contact.consent_changed
  • contact.erased
  • template.updated
  • channel.status_changed
  • channel.health_changed
  • conversation.updated (off by default: subscribe the endpoint to it explicitly)
  • contact.reachability_changed
  • contact.updated (off by default: subscribe the endpoint to it explicitly)
  • account.service_stop_scheduled
  • account.service_resumed
  • template.category_changed
  • channel.quality_changed
  • template.category_change_closed
  • webhook.test
api_versionrequired"v1"
created_atrequiredTimestamp
team_idrequiredId
channelrequiredobject | null
testrequiredboolean

True only for test events (the webhook page's and the API's test event and probe, and the optional weekly test event).

datarequiredobject

WebhookEndpointList

WebhookEndpointList: Fields
FieldTypeDescription
objectrequired"list"
datarequiredarray of WebhookEndpoint
next_cursorrequiredstring | 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.

WebhookEndpoint: Fields
FieldTypeDescription
objectrequired"webhook_endpoint"
idrequiredId
urlrequiredstring
eventsrequiredarray of string

The subscribed event types (webhook.test always goes and is not listed).

channel_idrequiredId | null

The channel filter; null for every channel.

orderingrequiredstring
  • best_effort
  • strict
max_in_flightrequiredinteger
api_versionrequiredstring
staterequiredstring

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.

  • pending_verification
  • active
  • failing
  • suspended
  • disabled
consecutive_failuresrequiredinteger
failing_sincerequiredNullableTimestamp
suspended_atrequiredNullableTimestamp
suspended_reasonrequiredstring | null

gone (the endpoint answered 410) or failing (72 hours).

disabled_atrequiredNullableTimestamp
last_success_atrequiredNullableTimestamp
last_failure_atrequiredNullableTimestamp
verificationrequiredobject

Whether a test event and the wrong-signature probe passed within the last hour, and their last HTTP status.

verification.test_passedrequiredboolean
verification.probe_passedrequiredboolean
verification.probe_requiredrequiredboolean

Activation needs the probe too (a new endpoint or a new address).

verification.last_test_statusrequiredinteger | null
verification.last_probe_statusrequiredinteger | null
secret_rotating_untilrequiredstring | null

Until when the secret replaced by the last rotation still signs; null when none does.

pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$

weekly_testrequiredobject

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.enabledrequiredboolean
weekly_test.last_sent_atrequiredNullableTimestamp
weekly_test.last_statusrequiredinteger | null
weekly_test.failed_atrequiredNullableTimestamp
secretrequiredstring | null

whsec_ and 44 base64 characters; only in the answer that creates the endpoint and in the answer of a rotation.

pattern ^whsec_[A-Za-z0-9+/]{43}=$

created_atrequiredTimestamp

WebhookEndpointCreateRequest

WebhookEndpointCreateRequest: Fields
FieldTypeDescription
urlrequiredstring

Your https address on port 443, at most 2048 characters.

max length 2048

eventsarray 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.

  • message.received
  • message.status
  • message.created
  • contact.identity_changed
  • contact.consent_changed
  • contact.erased
  • template.updated
  • channel.status_changed
  • channel.health_changed
  • conversation.updated (off by default: subscribe the endpoint to it explicitly)
  • contact.reachability_changed
  • contact.updated (off by default: subscribe the endpoint to it explicitly)
  • account.service_stop_scheduled
  • account.service_resumed
  • template.category_changed
  • channel.quality_changed
  • template.category_change_closed
channel_idId | null

Only the events of this channel; null for every channel.

orderingstring

default "best_effort"

  • best_effort
  • strict
max_in_flightinteger

min 1 · max 32 · default 8

weekly_testboolean

Send a test event every week (a failure is only a warning).

default false

WebhookEndpointUpdateRequest

Only the fields you send change.

WebhookEndpointUpdateRequest: Fields
FieldTypeDescription
urlstring

A new address sends the endpoint back to verification.

max length 2048

eventsarray of string
  • message.received
  • message.status
  • message.created
  • contact.identity_changed
  • contact.consent_changed
  • contact.erased
  • template.updated
  • channel.status_changed
  • channel.health_changed
  • conversation.updated (off by default: subscribe the endpoint to it explicitly)
  • contact.reachability_changed
  • contact.updated (off by default: subscribe the endpoint to it explicitly)
  • account.service_stop_scheduled
  • account.service_resumed
  • template.category_changed
  • channel.quality_changed
  • template.category_change_closed
channel_idId | null
orderingstring
  • best_effort
  • strict
max_in_flightinteger

min 1 · max 32

weekly_testboolean

WebhookEndpointTestRequest

WebhookEndpointTestRequest: Fields
FieldTypeDescription
typestring

The event type of the sample (webhook.test if left out).

  • message.received
  • message.status
  • message.created
  • contact.identity_changed
  • contact.consent_changed
  • contact.erased
  • template.updated
  • channel.status_changed
  • channel.health_changed
  • conversation.updated (off by default: subscribe the endpoint to it explicitly)
  • contact.reachability_changed
  • contact.updated (off by default: subscribe the endpoint to it explicitly)
  • account.service_stop_scheduled
  • account.service_resumed
  • template.category_changed
  • channel.quality_changed
  • template.category_change_closed
  • webhook.test

WebhookEndpointCheck

The result of a test event or of the wrong-signature probe.

WebhookEndpointCheck: Fields
FieldTypeDescription
objectrequired"webhook_endpoint_check"
endpoint_idrequiredId
kindrequiredstring
  • test
  • probe
typerequiredstring
passedrequiredboolean

test: your server answered 2xx. probe: your server refused the wrong signature (any answer other than 2xx).

statusrequiredinteger | null

The HTTP status; null when no answer came (for example a refused address or a timeout).

latency_msrequiredinteger
response_excerptrequiredstring | null

The first characters of your server's answer.

errorrequiredstring | null

Why the request failed, the address masked; null when your server answered.

checked_atrequiredTimestamp

DeletedWebhookEndpoint

DeletedWebhookEndpoint: Fields
FieldTypeDescription
objectrequired"webhook_endpoint"
idrequiredId
deletedrequiredtrue

Generated from openapi.json (commit a1fec8942, 19 November 2026) · Live OpenAPI document