Schemas

Every object the public operations send or return, generated from api/openapi.public.yaml.

BatchBody

Field	Type	Required	Description
products	array of ProductUpsertBody or null	yes	(min 1 items, max 500 items)

BatchResultBody

Field	Type	Required	Description
results	array of UpsertResultBody	yes	In the order of the request

CallNoteBody

Field	Type	Required	Description
callId	string (uuid)	yes
missed	boolean	yes	Nobody answered the call
reason	string		How the call ended, such as no_answer or cancelled

CatalogBody

Field	Type	Required	Description
errorCode	string
errorMessage	string
metaCatalogId	string
status	"pending" | "no_number" | "active" | "failed"	yes	pending: not set up with Meta yet; no_number: the store has no WhatsApp number connected; failed: it could not be set up, errorCode and errorMessage say why

CategoriesBody

Field	Type	Required	Description
categories	array of CategoryBody	yes

CategoriesInputBody

Field	Type	Required	Description
categories	array of CategoryInputBody or null	yes	In display order; categories left out keep their names and follow these (min 1 items, max 500 items)

CategoryBody

Field	Type	Required	Description
externalId	string	yes
name	string	yes
position	integer (int32)	yes	Display order, from 0

CategoryInputBody

Field	Type	Required	Description
externalId	string	yes	(min length 1, max length 100, pattern ^[A-Za-z0-9._:-]+$)
name	string	yes	(min length 1, max length 120)

CategoryRefBody

Field	Type	Required	Description
externalId	string	yes
name	string	yes

ChoiceBody

Field	Type	Required	Description
description	string
id	string
title	string	yes

ContactBody

Field	Type	Required	Description
externalRef	string		The business’s own id for this contact
id	string (uuid)	yes
language	"en" | "so" | "ar"	yes	Language of the automatic menu
name	string	yes
phone	string	yes	E.164
tags	array of string	yes
whatsappName	string		The name on the customer’s WhatsApp profile

ConversationBody

Field	Type	Required	Description
assigneeMemberId	string (uuid)
closedAt	string (date-time)
contact	ContactBody	yes
createdAt	string (date-time)	yes
id	string (uuid)	yes
lastMessage	LastMessageBody
lastMessageAt	string (date-time)	yes
numberId	string (uuid)	yes	The business WhatsApp number the customer wrote to
pinned	boolean	yes
routingDeadline	string (date-time)		When a chat waiting for a menu choice goes to the default team
routingState	"awaiting_menu" | "routed"	yes
snoozedUntil	string (date-time)
status	"open" | "closed" | "snoozed"	yes
teamId	string (uuid)		Absent while the customer has not chosen a team from the menu
unreadCount	integer (int64)	yes
updatedAt	string (date-time)	yes
windowExpiresAt	string (date-time)		Until then any message can be sent; after it only an approved template

ConversationListOutputBody

Field	Type	Required	Description
conversations	array of ConversationBody	yes
next	string		Pass as cursor for the next page; absent on the last page

CreateInputBody2

Field	Type	Required	Description
category	"marketing" | "utility" | "authentication"	yes
definition	TemplateDefinitionBody	yes
language	string	yes	A WhatsApp language code, such as en_US, so or ar (min length 2, max length 16)
name	string	yes	Lowercase letters, digits and underscores (min length 1, max length 512, pattern ^[a-z0-9_]+$)

CreatePartnerEndpointInputBody

Field	Type	Required	Description
description	string		(max length 200)
events	array of string	yes	Event types from GET /partner/webhook-event-types (min 1 items, max 64 items)
url	string	yes	An https URL on the public internet (min length 8, max length 2048)

CreateSessionInputBody

Field	Type	Required	Description
embedOrigin	string		Sent by the Nexafon embed page: the origin of the page that frames it (max length 300)
publishableKey	string	yes	pk_live_… or pk_test_…, or a partner’s ppk_live_… or ppk_test_… (min length 1, max length 128)
userToken	string	yes	A JWT (HS256) your server signs with one of the workspace’s secret keys of the same mode: sub (your user id), jti (new for each token) and exp (at most 10 minutes ahead) are required; name, email, email_verified (a boolean) and role are optional. The first time a user signs in, email is required and email_verified must be true: that email links the user to the member with the same email, or to a new member. Later sign-ins use that link and ignore the email. With a partner’s publishable key, the partner’s server signs it with one of the partner’s secret keys (psk_…) of the same mode that has the partner.stores:manage scope, and the session acts with no more than that key’s store permissions: sub (the partner’s user id), name, jti and exp are required, email and locale (en, so or ar) optional, and stores lists 1 to 50 of the partner’s stores as {externalRef, role, teams?}: role is one of owner, admin, supervisor, agent or viewer, and teams, when present, the store’s team ids the user is in. The user becomes or stays an active member of each store with that role (min length 1, max length 32768)

CreateWebhookEndpointInputBody

Field	Type	Required	Description
description	string		(max length 200)
events	array of string	yes	Event types from GET /webhook-event-types (min 1 items, max 64 items)
url	string	yes	An https URL on the public internet (min length 8, max length 2048)

DayHoursBody

Field	Type	Required	Description
closes	string	yes	Closing time, HH:MM, after the opening time (pattern ^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$)
day	"sat" | "sun" | "mon" | "tue" | "wed" | "thu" | "fri"	yes
opens	string	yes	Opening time, HH:MM in the workspace’s time zone (pattern ^([01][0-9]|2[0-3]):[0-5][0-9]$)

DeliveryAreaBody

Field	Type	Required	Description
active	boolean	yes	Only active areas are offered in checkout
feeCents	integer (int64)	yes	The delivery fee in US cents (min 0, max 100000000000)
id	string (uuid)		Absent for a new area
name	string	yes	As the customer picks it in checkout (min length 1, max length 30)

DeliveryBody

Field	Type	Required	Description
areas	array of DeliveryAreaBody	yes	In the order checkout lists them; an area left out is removed (max 100 items)
deliveryEnabled	boolean	yes
freeDeliveryAboveCents	integer (int64)		Delivery is free from this order amount (after discounts) in cents; never free when absent (min 0, max 100000000000)
notifyStatuses	array of string	yes	Order statuses the customer gets a WhatsApp message for: awaiting_payment, paid, preparing, out_for_delivery, delivered, cancelled, refunded (max 7 items)
pickupAddress	string	yes	Where pickup orders are collected; shown to the customer (max length 500)
pickupEnabled	boolean	yes
requestLocation	boolean	yes	Ask the customer for a location pin after checkout when they chose delivery
saved	boolean	yes	false while the store has not saved its delivery settings and the defaults apply

DeliverySettingsBody

Field	Type	Required	Description
areas	array of DeliveryAreaBody	yes	In the order checkout lists them; an area left out is removed (max 100 items)
deliveryEnabled	boolean	yes
freeDeliveryAboveCents	integer (int64)		Delivery is free from this order amount (after discounts) in cents; never free when absent (min 0, max 100000000000)
notifyStatuses	array of string	yes	Order statuses the customer gets a WhatsApp message for: awaiting_payment, paid, preparing, out_for_delivery, delivered, cancelled, refunded (max 7 items)
pickupAddress	string	yes	Where pickup orders are collected; shown to the customer (max length 500)
pickupEnabled	boolean	yes
requestLocation	boolean	yes	Ask the customer for a location pin after checkout when they chose delivery

EditInputBody

Field	Type	Required	Description
category	"marketing" | "utility"		Unchanged when absent
definition	TemplateDefinitionBody	yes

FieldError

Field	Type	Required	Description
location	string		Where the error occurred, e.g. ‘body.name’ or ‘path.id’
message	string	yes	What is wrong with the value
value	any		The value that was rejected

FlowButtonBody

Field	Type	Required	Description
cta	string	yes	The button that opens the Flow

FlowFieldBody

Field	Type	Required	Description
name	string	yes
value	string	yes	Text, a number, true or false, or JSON for a list or group

FlowReplyBody

Field	Type	Required	Description
fields	array of FlowFieldBody	yes	The answers, sorted by name
name	string		The Flow’s name

LastMessageBody

Field	Type	Required	Description
deleted	boolean	yes
direction	"inbound" | "outbound" | "internal"	yes
status	"received" | "pending" | "sent" | "delivered" | "read" | "failed" | "saved"	yes
text	string	yes	Text or caption; empty for a deleted message
type	string	yes

ListMembersOutputBody

Field	Type	Required	Description
members	array of MemberBody	yes

ListOutputBody

Field	Type	Required	Description
count	integer (int64)	yes	Recordings that count toward the plan limit; defaults are not counted
limit	integer (int64)	yes	Most recordings the plan allows; 0 when unlimited is true
recordings	array of RecordingBody	yes
unlimited	boolean	yes	The plan allows any number of recordings

ListOutputBody3

Field	Type	Required	Description
next	string		Pass as cursor for the next page; absent on the last page
syncError	string		Why the last sync failed
syncedAt	string (date-time)		When the templates were last read in full from Meta
templates	array of TemplateBody	yes	By name, then language

ListTeamsOutputBody

Field	Type	Required	Description
teams	array of TeamDetailBody	yes

MediaBody

Field	Type	Required	Description
caption	string
fileId	string (uuid)		Set once the file is stored; open it with the message’s media link
filename	string
mimeType	string
status	"pending" | "ready" | "failed"	yes	pending while an inbound file is being copied from WhatsApp
voice	boolean		A voice note recorded in WhatsApp

MediaSendBody

Field	Type	Required	Description
fileId	string (uuid)	yes	A file uploaded through the files API
filename	string		Shown to the customer for documents (max length 240)

MemberBody

Field	Type	Required	Description
createdAt	string (date-time)	yes
email	string (email)	yes
id	string (uuid)	yes
joinedAt	string (date-time)
lastActiveAt	string (date-time)		When one of the member’s sessions was last refreshed, to the day; absent without a session
name	string	yes	The name on the member’s account; empty when they have not set one
role	string	yes
status	"invited" | "active" | "disabled"	yes
teams	array of TeamBody	yes	The teams the member belongs to; they scope what the member sees
userId	string	yes

MenuBody

Field	Type	Required	Description
body	string	yes
headerImage	string		An https link to the image shown above the buttons
listButton	string		Set when the options show as a list instead of buttons
options	array of MenuOptionBody	yes

MenuOptionBody

Field	Type	Required	Description
id	string	yes
title	string	yes

MessageBody

Field	Type	Required	Description
call	CallNoteBody		A WhatsApp call of the customer’s
choice	ChoiceBody		The customer’s tap on a button or list row
clientMsgId	string
conversationId	string (uuid)	yes
createdAt	string (date-time)	yes
deleted	boolean	yes
deliveredAt	string (date-time)
direction	"inbound" | "outbound" | "internal"	yes	internal: a note only the team sees
errorCode	string
errorMessage	string		Why the message failed, written for the agent
failedAt	string (date-time)
flow	FlowButtonBody		A business message whose button opens a WhatsApp Flow
flowReply	FlowReplyBody		The customer’s answers to a WhatsApp Flow
forwarded	boolean
id	string (uuid)	yes
location	MessageLocationBody
locationRequest	boolean		A business message asking the customer to share their location
media	MediaBody
menu	MenuBody		Buttons or list sent by the business
order	OrderBody		A cart the customer sent from the catalog
products	MessageProductsBody		Items of the store’s catalog the shop sent
reactions	array of ReactionBody	yes
readAt	string (date-time)
replyToMessageId	string (uuid)
sentAt	string (date-time)
sentByMemberId	string (uuid)		Absent for the customer’s messages and automatic ones
status	"received" | "pending" | "sent" | "delivered" | "read" | "failed" | "saved"	yes	pending until WhatsApp accepts the message; statuses never go back
template	TemplateRefBody
text	string	yes	Text, caption or note; empty for a deleted message
type	"text" | "image" | "video" | "audio" | "document" | "sticker" | "location" | "template" | "reaction" | "interactive" | "contacts" | "unsupported" | "note" | "call" | "order"	yes

MessageLocationBody

Field	Type	Required	Description
address	string
latitude	number (double)	yes
longitude	number (double)	yes
name	string

MessageProductSectionBody

Field	Type	Required	Description
retailerIds	array of string	yes	The catalog items’ retailer ids
title	string

MessageProductsBody

Field	Type	Required	Description
header	string
kind	"product" | "product_list" | "carousel" | "catalog_message"	yes	product: one item; product_list: sections of items; carousel: a card per item; catalog_message: the whole catalog, with the item shown as its thumbnail
sections	array of MessageProductSectionBody	yes

NewStoreBody

Field	Type	Required	Description
country	string	yes	ISO 3166-1 alpha-2, such as SO (pattern ^[A-Za-z]{2}$)
externalRef	string	yes	The partner’s own id for the store; creating again with the same value returns the same store (min length 1, max length 255, pattern ^[A-Za-z0-9._:-]+$)
locale	"en" | "so" | "ar"	yes
name	string	yes	(min length 1, max length 120)
owner	StoreOwnerBody	yes
timezone	string	yes	IANA time zone, such as Africa/Mogadishu (min length 1, max length 64)

NumberListBody

Field	Type	Required	Description
createdAt	string (date-time)	yes
id	string (uuid)	yes
kind	"uploaded" | "past_orders"	yes
minOrders	integer (int32)
name	string	yes
phones	array of string or null		Only when one list is read
size	integer (int32)	yes	Numbers in an uploaded list
updatedAt	string (date-time)	yes
usedBy	integer (int64)	yes	Promotions that use the list

NumberListFields

Field	Type	Required	Description
kind	"uploaded" | "past_orders"	yes	uploaded: the numbers given; past_orders: every customer with at least minOrders paid orders
minOrders	integer (int32)		Required for past_orders (min 1, max 1000)
name	string	yes	(min length 1, max length 80)
phones	array of string or null		International numbers with their country code, for uploaded (max 10000 items)

NumberListsBody

Field	Type	Required	Description
lists	array of NumberListBody	yes	By name

OrderBody

Field	Type	Required	Description
catalogId	string
items	array of OrderItemBody	yes
text	string		The customer’s note with the cart

OrderCancelBody

Field	Type	Required	Description
reason	string		Why, such as out of stock (max length 500)

OrderItemBody

Field	Type	Required	Description
currency	string		ISO 4217 code
itemPrice	string		Decimal price per item as WhatsApp reported it; the order logic prices from the catalog
productRetailerId	string	yes	The catalog item’s retailer id
quantity	integer (int64)	yes

OrderStatusBody

Field	Type	Required	Description
note	string		Kept in the order’s history; for cancelled, the reason (max length 500)
status	"preparing" | "out_for_delivery" | "delivered" | "cancelled"	yes	Payment and checkout set the other statuses

PartnerAppearanceBody

Field	Type	Required	Description
colorMode	"light" | "dark" | "auto"	yes
font	"ibm_plex_sans" | "inter" | "system"	yes
primaryColor	string	yes	Brand colour, such as #0f766e (pattern ^#[0-9a-fA-F]{6}$)
radius	integer (int32)	yes	Corner radius in pixels (min 0, max 24)

PartnerMemberBody

Field	Type	Required	Description
externalRef	string	yes	The partner’s own id for the store
memberId	string (uuid)	yes
partnerUserId	string	yes	The partner’s id for the user: the sub of its user tokens
role	string	yes
status	"active" | "disabled"	yes
teamIds	array of string (uuid)	yes
workspaceId	string (uuid)	yes

PartnerPlanBody

Field	Type	Required	Description
key	string	yes
name	string	yes	Empty when the plan no longer exists

PartnerPlanFeatureBody

Field	Type	Required	Description
enabled	boolean	yes
key	string	yes
limit	integer (int64)		Limit features: the most allowed; absent means no limit

PartnerProfileBody

Field	Type	Required	Description
defaultPlan	PartnerPlanBody	yes	The plan every new store starts on
features	array of PartnerPlanFeatureBody	yes	The features of the default plan’s published version
id	string (uuid)	yes
name	string	yes
slug	string	yes
status	"active" | "suspended"	yes

PreviewInputBody

Field	Type	Required	Description
components	array of TemplateComponentBody		The parameters, exactly as sending the template takes them (max 12 items)

PreviewOutputBody

Field	Type	Required	Description
body	string	yes
buttons	array of TemplatePreviewButtonBody	yes
footer	string
header	TemplatePreviewHeaderBody
templateId	string	yes
text	string	yes	Header, body and footer as plain text

Problem

Field	Type	Required	Description
code	string	yes	A stable, machine-readable error code
detail	string		A human-readable explanation of this occurrence
errors	array of FieldError or null		The individual problems, such as one per invalid field
requestId	string		The request id to quote when reporting the problem
status	integer (int64)	yes	The HTTP status code
title	string	yes	The HTTP status text
type	string (uri)	yes	A link to the documentation of this error code, or about:blank

ProductBody

Field	Type	Required	Description
active	boolean	yes
availability	"in_stock" | "out_of_stock"	yes
category	CategoryRefBody
currency	"USD"	yes
description	string	yes
externalId	string	yes
imageUrls	array of string	yes
name	string	yes
priceCents	integer (int64)	yes
saleEndsAt	string (date-time)
salePriceCents	integer (int64)
saleStartsAt	string (date-time)
stock	integer (int32)
sync	SyncBody	yes	The product’s worst item: a rejected size shows on the product
updatedAt	string (date-time)	yes
variants	array of VariantViewBody	yes

ProductFields

Field	Type	Required	Description
active	boolean		false keeps the product but takes it out of the WhatsApp catalog; true when absent
availability	"in_stock" | "out_of_stock"		(default "in_stock")
categoryExternalId	string		A category upserted before; none when absent (max length 100, pattern ^[A-Za-z0-9._:-]*$)
currency	"USD"		(default "USD")
description	string		(max length 5000)
imageUrls	array of string or null	yes	HTTPS URLs on the public internet; Meta fetches them, Nexafon does not host them. The first is the main image (min 1 items, max 10 items)
name	string	yes	(min length 1, max length 200)
priceCents	integer (int64)	yes	In US cents (min 0, max 100000000000)
saleEndsAt	string (date-time)		Open-ended when absent
salePriceCents	integer (int64)		Below priceCents; shown while the sale window is open (min 0, max 100000000000)
saleStartsAt	string (date-time)		Open from now when absent
stock	integer (int32)		Absent when the partner does not count stock; 0 shows the product out of stock (min 0)
variants	array of VariantBody or null		Sizes or colours, each its own catalog item grouped under the product; the product itself is the one item when absent (max 50 items)

ProductUpsertBody

Field	Type	Required	Description
active	boolean		false keeps the product but takes it out of the WhatsApp catalog; true when absent
availability	"in_stock" | "out_of_stock"		(default "in_stock")
categoryExternalId	string		A category upserted before; none when absent (max length 100, pattern ^[A-Za-z0-9._:-]*$)
currency	"USD"		(default "USD")
description	string		(max length 5000)
externalId	string	yes	The partner’s own id for the product (min length 1, max length 100, pattern ^[A-Za-z0-9._:-]+$)
imageUrls	array of string or null	yes	HTTPS URLs on the public internet; Meta fetches them, Nexafon does not host them. The first is the main image (min 1 items, max 10 items)
name	string	yes	(min length 1, max length 200)
priceCents	integer (int64)	yes	In US cents (min 0, max 100000000000)
saleEndsAt	string (date-time)		Open-ended when absent
salePriceCents	integer (int64)		Below priceCents; shown while the sale window is open (min 0, max 100000000000)
saleStartsAt	string (date-time)		Open from now when absent
stock	integer (int32)		Absent when the partner does not count stock; 0 shows the product out of stock (min 0)
variants	array of VariantBody or null		Sizes or colours, each its own catalog item grouped under the product; the product itself is the one item when absent (max 50 items)

ProductsBody

Field	Type	Required	Description
catalog	CatalogBody	yes
next	string		Pass as cursor for the next page; absent on the last page
products	array of ProductBody	yes	By name

PromotionBody

Field	Type	Required	Description
active	boolean	yes
amountOffCents	integer (int64)		In US cents: per unit for a flash sale, off the products in scope otherwise (min 1, max 100000000000)
categoryExternalIds	array of string	yes
code	string		The coupon code; compared without case (max length 32)
combinable	boolean		Adds to the other combinable promotions; otherwise only the best discount applies
createdAt	string (date-time)	yes
endsAt	string (date-time)		Open-ended when absent
id	string (uuid)	yes
kind	"flash_sale" | "number_list" | "coupon"	yes	flash_sale: lowers the price of the products in scope inside its window and shows in the WhatsApp catalog; number_list: a discount for the numbers of a list; coupon: applies when the customer enters its code at checkout
maxPerCustomer	integer (int32)		A coupon’s or number-list discount’s uses per customer number (min 1)
maxRedemptions	integer (int32)		A coupon’s or number-list discount’s uses across all customers (min 1)
minSubtotalCents	integer (int64)		Applies only from this cart subtotal in cents (min 0, max 100000000000)
name	string	yes	(min length 1, max length 120)
numberListId	string (uuid)		Only the numbers of this list get it; required for number_list
open	boolean	yes	Active and inside its window now
percentOff	integer (int32)		Exactly one of percentOff and amountOffCents (min 1, max 100)
productExternalIds	array of string	yes
redemptions	integer (int64)	yes	Orders that used the coupon
scope	"all" | "products" | "categories"	yes
startsAt	string (date-time)		Open from now when absent
updatedAt	string (date-time)	yes

PromotionFields

Field	Type	Required	Description
active	boolean		true when absent
amountOffCents	integer (int64)		In US cents: per unit for a flash sale, off the products in scope otherwise (min 1, max 100000000000)
categoryExternalIds	array of string or null		The categories’ external ids when scope is categories (max 100 items)
code	string		The coupon code; compared without case (max length 32)
combinable	boolean		Adds to the other combinable promotions; otherwise only the best discount applies
endsAt	string (date-time)		Open-ended when absent
kind	"flash_sale" | "number_list" | "coupon"	yes	flash_sale: lowers the price of the products in scope inside its window and shows in the WhatsApp catalog; number_list: a discount for the numbers of a list; coupon: applies when the customer enters its code at checkout
maxPerCustomer	integer (int32)		A coupon’s or number-list discount’s uses per customer number (min 1)
maxRedemptions	integer (int32)		A coupon’s or number-list discount’s uses across all customers (min 1)
minSubtotalCents	integer (int64)		Applies only from this cart subtotal in cents (min 0, max 100000000000)
name	string	yes	(min length 1, max length 120)
numberListId	string (uuid)		Only the numbers of this list get it; required for number_list
percentOff	integer (int32)		Exactly one of percentOff and amountOffCents (min 1, max 100)
productExternalIds	array of string or null		The products’ external ids when scope is products (max 500 items)
scope	"all" | "products" | "categories"		(default "all")
startsAt	string (date-time)		Open from now when absent

PromotionsBody

Field	Type	Required	Description
promotions	array of PromotionBody	yes	Newest first

ReactionBody

Field	Type	Required	Description
by	"contact" | "member"	yes
emoji	string	yes
memberId	string (uuid)

RecordingBody

Field	Type	Required	Description
createdAt	string (date-time)	yes
createdBy	string	yes
durationMs	integer (int64)		Length of the playable audio, measured by the server
failureCode	"too_short" | "too_long" | "unreadable" | "processing_error"
failureReason	string		Why the last upload failed, in English
id	string (uuid)	yes
isDefault	boolean	yes	The workspace’s fallback for its kind and language; it can be replaced but not deleted
kind	"greeting" | "option" | "fallback_closed" | "fallback_prayer" | "fallback_missed" | "hold" | "custom"	yes
language	"en" | "so" | "ar"		Absent when it plays for callers of any language
name	string	yes
playable	boolean	yes	Calls can play it. A replacement that is processing or failed leaves the previous audio playing.
size	integer (int64)		Size in bytes of the playable audio as uploaded
source	"recorded" | "uploaded" | "default"	yes
status	"processing" | "ready" | "failed"	yes	State of the last upload
updatedAt	string (date-time)	yes
uses	array of UseBody	yes	Where it plays; a recording in use can’t be deleted

SDKSessionBody

Field	Type	Required	Description
appearance	PartnerAppearanceBody		An exchange with a partner’s key: the partner’s default appearance for its stores’ embeds
expiresAt	string (date-time)	yes	Refresh the session before this
memberId	string (uuid)		A workspace’s session: the member it acts as
mode	"live" | "test"	yes
name	string		An exchange only: the user’s name from the user token
refreshUntil	string (date-time)	yes	Refreshes keep the session going until this; then exchange a new user token
sessionId	string (uuid)	yes
stores	array of SDKSessionStoreBody		An exchange with a partner’s key: the stores the session opens, in the user token’s order; GET /api/v1/me/workspaces lists them at any time
token	string	yes	The session token. Keep it in memory (web) or in the Keychain or Keystore (mobile), never in localStorage, and send it as Authorization: Bearer
userId	string	yes
workspaceId	string (uuid)		A workspace’s session: its workspace

SDKSessionStoreBody

Field	Type	Required	Description
externalRef	string	yes	The partner’s own id for the store
memberId	string (uuid)	yes
name	string	yes
role	string	yes	The user’s role key in the store, such as agent
workspaceId	string (uuid)	yes

SendBody

Field	Type	Required	Description
clientMsgId	string	yes	Your id for this message: sending it again returns the message already queued instead of sending twice (min length 1, max length 64, pattern ^[A-Za-z0-9._:-]+$)
media	MediaSendBody
replyToMessageId	string (uuid)		Quote this message
template	TemplateSendBody		The only kind of message allowed outside the 24-hour window
text	string		The message, or the caption of an image, video or document (max length 4096)
type	"text" | "image" | "video" | "audio" | "document" | "sticker" | "template"	yes

StartInputBody

Field	Type	Required	Description
message	SendBody	yes	An approved template
phone	string	yes	The customer’s number with its country code (min length 3, max length 32)
teamId	string (uuid)		The team the conversation belongs to; the routing’s default team when it is one of yours

StartOutputBody

Field	Type	Required	Description
conversation	ConversationBody	yes
message	MessageBody	yes

StoreBody

Field	Type	Required	Description
closedAt	string (date-time)		Set while the partner has closed the store
country	string	yes	ISO 3166-1 alpha-2
createdAt	string (date-time)	yes
externalRef	string	yes	The partner’s own id for the store
locale	"en" | "so" | "ar"	yes
name	string	yes
owner	StoreOwnerBody	yes
status	"trialing" | "active" | "past_due" | "suspended" | "cancelled"	yes
timezone	string	yes
workspaceId	string (uuid)	yes	Use it in /api/v1/workspaces/{workspaceId}/… to act in the store

StoreChangeBody

Field	Type	Required	Description
name	string		(min length 1, max length 120)
status	"active" | "suspended"		suspended closes the store and keeps its data; active reopens a store the partner closed

StoreOrderBody

Field	Type	Required	Description
address	string
cancelReason	string
checkedOutAt	string (date-time)
contactPhone	string
conversationId	string (uuid)
couponCode	string
createdAt	string (date-time)	yes
currency	"USD"	yes
customerName	string
customerPhone	string	yes
deliveryArea	string
deliveryFeeCents	integer (int64)	yes
discountCents	integer (int64)	yes
discountReason	string		The promotions that make up the discount
events	array of StoreOrderEventBody or null		The order’s history, oldest first; on a single order
fulfilment	"delivery" | "pickup"		Chosen in checkout
id	string (uuid)	yes
itemCount	integer (int64)	yes
items	array of StoreOrderItemBody or null		On a single order
location	StoreOrderLocationBody		The pin the customer shared after checkout
nextStatuses	array of string	yes	The statuses the store may set now
note	string		Cart items that were left out, and why
number	integer (int64)	yes	The store’s own order number
status	"new" | "awaiting_payment" | "paid" | "preparing" | "out_for_delivery" | "delivered" | "cancelled" | "refunded"	yes
subtotalCents	integer (int64)	yes
teamId	string (uuid)
totalCents	integer (int64)	yes	subtotalCents - discountCents + deliveryFeeCents, computed by Nexafon
updatedAt	string (date-time)	yes

StoreOrderEventBody

Field	Type	Required	Description
actorId	string
actorType	"member" | "partner_key" | "api_key" | "customer" | "system"	yes
at	string (date-time)	yes
fromStatus	string
kind	"created" | "summary_sent" | "status_changed" | "checkout" | "location" | "customer_notified" | "customer_not_notified" | "payment_failed"	yes
note	string
toStatus	string

StoreOrderItemBody

Field	Type	Required	Description
color	string
name	string	yes
productExternalId	string	yes
quantity	integer (int32)	yes
retailerId	string	yes	The WhatsApp retailer_id the customer ordered
size	string
unitPriceCents	integer (int64)	yes	The store’s price when the order was priced, in US cents

StoreOrderLocationBody

Field	Type	Required	Description
latitude	number (double)	yes
longitude	number (double)	yes

StoreOrdersBody

Field	Type	Required	Description
next	string		Pass as cursor for the next page; absent on the last page
orders	array of StoreOrderBody	yes	Newest first

StoreOwnerBody

Field	Type	Required	Description
email	string (email)	yes	(max length 320)
name	string	yes	(min length 1, max length 120)

StorePayPointBody

Field	Type	Required	Description
available	boolean	yes	PayPoint is configured on this server; without it no store takes payments
last4	string	yes	The saved key’s last four characters, all of it that is ever shown
merchantId	string	yes
options	array of StoreWalletBody	yes	Every wallet a store can take, in the order customers see them
saved	boolean	yes	The store’s own PayPoint key is saved
updatedAt	string (date-time)		When the key was last saved
wallets	array of "evc_plus" | "zaad" | "sahal" | "jeeb" | "edahab" | "premier_wallet"	yes	The wallets customers may pay with, in the order they see them

StorePayPointKeyBody

Field	Type	Required	Description
apiKey	string	yes	The store’s own PayPoint API key. It is stored encrypted and never returned. (min length 1, max length 512)
merchantId	string	yes	The store’s PayPoint merchant id (min length 1, max length 100, pattern ^[A-Za-z0-9_.-]+$)

StorePayPointKeySavedBody

Field	Type	Required	Description
last4	string	yes	The key’s last four characters, all of it that is ever shown
saved	boolean	yes

StorePayPointKeyTestBody

Field	Type	Required	Description
ok	boolean	yes	PayPoint accepted the key; nobody was charged
reason	"refused" | "unreachable"		refused: PayPoint does not accept the key; unreachable: PayPoint did not answer, try again

StorePayPointWalletsBody

Field	Type	Required	Description
wallets	array of "evc_plus" | "zaad" | "sahal" | "jeeb" | "edahab" | "premier_wallet"	yes	The wallets customers may pay with in the WhatsApp checkout (max 6 items)

StoreWalletBody

Field	Type	Required	Description
id	"evc_plus" | "zaad" | "sahal" | "jeeb" | "edahab" | "premier_wallet"	yes
name	string	yes	The wallet’s brand name, the same in every language

StoresBody

Field	Type	Required	Description
next	string		Pass as cursor for the next page; absent on the last page
stores	array of StoreBody	yes	Newest first

SyncBody

Field	Type	Required	Description
lastSyncedAt	string (date-time)		When the item was last pushed to Meta
reason	string		Meta’s rejection reason, or why the push failed
status	"queued" | "in_review" | "approved" | "rejected" | "failed" | "inactive"	yes	queued: waiting for the next push, within a minute; in_review: Meta is reviewing; failed: Meta refused the push; inactive: not in the catalog

SyncOutputBody

Field	Type	Required	Description
syncError	string
syncedAt	string (date-time)		When the templates were last read in full from Meta

TeamBody

Field	Type	Required	Description
id	string (uuid)	yes
role	"member" | "lead"	yes

TeamDetailBody

Field	Type	Required	Description
color	"chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5"	yes	Theme token shown next to the team’s conversations
createdAt	string (date-time)	yes
id	string (uuid)	yes
isDefault	boolean	yes	Routing sends everything it does not route elsewhere to this team
members	array of TeamMemberBody	yes	Members in ring order (min 1 items, max 200 items)
name	string	yes	(min length 1, max length 80)
queue	TeamQueueBody	yes
updatedAt	string (date-time)	yes
workingHours	array of DayHoursBody or null	yes	Open days; a day that is not listed is closed. null means always open. (max 7 items)

TeamMemberBody

Field	Type	Required	Description
lead	boolean		Team leads see this team’s reports and can pick up its queued calls
memberId	string (uuid)	yes

TeamQueueBody

Field	Type	Required	Description
announcePositionSeconds	integer (int64)		How often a waiting caller hears their place in the queue, shorter than the longest wait; no announcements when unset (min 30, max 300)
closedRecordingId	string (uuid)		Recording played outside working hours; the workspace’s default closed message when unset
holdRecordingId	string (uuid)		Recording played while the caller waits; silence when unset
maxWaitSeconds	integer (int64)	yes	Longest wait in the queue (min 60, max 600)
missedRecordingId	string (uuid)		Recording played when nobody answers within the longest wait; the workspace’s default missed-call message when unset
ringTimeoutSeconds	integer (int64)	yes	After this the caller waits in the queue (min 30, max 60)
secondsPerPerson	integer (int64)	yes	How long each member rings with the priority strategy (min 5, max 60)
strategy	"all" | "priority"	yes	all rings every member at once; priority rings one member at a time in the members’ order

TemplateBody

Field	Type	Required	Description
category	"marketing" | "utility" | "authentication"	yes
createdAt	string (date-time)	yes
definition	TemplateDefinitionBody	yes
editPending	boolean	yes	An edit is on its way to Meta
errorCode	string		Why the last submission, edit or deletion failed
errorMessage	string
id	string	yes
language	string	yes
name	string	yes
parameterFormat	"positional" | "named"	yes
quality	string		Meta’s quality rating, such as GREEN
rejectedReason	string		Meta’s reason, for rejected templates
status	"submitting" | "submit_failed" | "pending" | "approved" | "rejected" | "paused" | "disabled" | "in_appeal" | "pending_deletion" | "limit_exceeded" | "archived" | "deleting"	yes
syncedAt	string (date-time)
updatedAt	string (date-time)	yes
usage	TemplateUsageBody

TemplateButtonBody

Field	Type	Required	Description
example	string		url: an example end of the address; copy_code: an example code (max length 200)
phoneNumber	string		For phone_number buttons, with its country code (max length 32)
text	string		(max length 25)
type	"quick_reply" | "url" | "phone_number" | "copy_code" | "otp" | "voice_call_request"	yes	voice_call_request asks the customer for permission to call them (Meta’s call permission request); it is always the last button
url	string		For url buttons; may end with {{1}}, filled in when sending (max length 2000)

TemplateComponentBody

Field	Type	Required	Description
index	integer (int64)		For buttons: the button’s position (min 0, max 9)
parameters	array of TemplateParameterBody or null		(max 20 items)
subType	"quick_reply" | "url" | "copy_code"		For buttons: url also fills a one-time password button
type	"header" | "body" | "button"	yes

TemplateCurrencyBody

Field	Type	Required	Description
amount1000	integer (int64)	yes	The amount times 1000: 12500 is 12.50
code	string	yes	ISO 4217 currency code, such as USD (max length 3)
fallbackValue	string	yes	Shown where WhatsApp cannot format the amount, such as $12.50 (max length 64)

TemplateDateTimeBody

Field	Type	Required	Description
fallbackValue	string	yes	The date or time as the customer reads it (max length 64)

TemplateDefinitionBody

Field	Type	Required	Description
body	TemplateTextBody	yes
buttons	array of TemplateButtonBody		(max 11 items)
footer	TemplateFooterBody
header	TemplateHeaderBody
unsupported	array of string		Parts Nexafon shows but cannot edit or send, such as carousels

TemplateExampleBody

Field	Type	Required	Description
name	string		The variable, for named variables; numbered ones take their examples in order (max length 64)
value	string	yes	(max length 200)

TemplateFooterBody

Field	Type	Required	Description
codeExpirationMinutes	integer (int64)		Authentication templates only (min 0, max 90)
text	string		(max length 60)

TemplateHeaderBody

Field	Type	Required	Description
examples	array of TemplateExampleBody		(max 1 items)
format	"text" | "image" | "video" | "document" | "location"	yes
sampleFileId	string (uuid)		For image, video and document headers: an uploaded file (files API, kind media) Meta reviews the header with
text	string		For text headers; at most one variable (max length 60)

TemplateLocationBody

Field	Type	Required	Description
address	string		(max length 200)
latitude	number (double)	yes	(min -90, max 90)
longitude	number (double)	yes	(min -180, max 180)
name	string		(max length 100)

TemplateMediaBody

Field	Type	Required	Description
filename	string		For documents (max length 240)
link	string (uri)	yes	A public https link WhatsApp downloads the file from (max length 2048)

TemplateParameterBody

Field	Type	Required	Description
couponCode	string		(max length 15)
currency	TemplateCurrencyBody
dateTime	TemplateDateTimeBody
document	TemplateMediaBody
image	TemplateMediaBody
location	TemplateLocationBody
parameterName	string		For templates with named variables (max length 64)
payload	string		(max length 1024)
text	string		(max length 1024)
type	"text" | "currency" | "date_time" | "image" | "video" | "document" | "location" | "payload" | "coupon_code"	yes	text, currency and date_time fill a variable; image, video, document and location fill a media or location header; payload is a quick-reply button’s payload; coupon_code fills a copy-code button
video	TemplateMediaBody

TemplatePreviewButtonBody

Field	Type	Required	Description
code	string		The code a copy-code or one-time password button copies
phoneNumber	string
text	string
type	string	yes
url	string		The full address, with the parameter filled in

TemplatePreviewHeaderBody

Field	Type	Required	Description
address	string
filename	string
format	string	yes
latitude	string
link	string
longitude	string
place	string
text	string

TemplateRefBody

Field	Type	Required	Description
category	string
language	string	yes
name	string	yes

TemplateSendBody

Field	Type	Required	Description
components	array of TemplateComponentBody or null		(max 10 items)
language	string	yes	Such as en_US (max length 16)
name	string	yes	An approved template of the workspace (max length 512)

TemplateTextBody

Field	Type	Required	Description
examples	array of TemplateExampleBody		(max 100 items)
securityRecommendation	boolean		Authentication templates: add Meta’s do-not-share line
text	string		Variables are {{1}}, {{2}}, … or lowercase names such as {{order_id}}; empty for authentication templates (max length 1024)

TemplateUsageBody

Field	Type	Required	Description
delivered	integer (int64)	yes
failed	integer (int64)	yes
pending	integer (int64)	yes	Queued and not yet accepted by WhatsApp
read	integer (int64)	yes
sent	integer (int64)	yes
since	string (date-time)	yes

ThreadOutputBody

Field	Type	Required	Description
messages	array of MessageBody	yes	The latest first
next	string		Pass as cursor for older messages; absent at the start of the conversation

TokenInputBody

Field	Type	Required	Description
token	string	yes	The current session token (min length 1, max length 128)

UpdatePartnerEndpointInputBody

Field	Type	Required	Description
description	string		(max length 200)
events	array of string or null		(min 1 items, max 64 items)
status	"active" | "disabled"		active turns a disabled endpoint back on
url	string		(min length 8, max length 2048)

UpdatePartnerMemberInputBody

Field	Type	Required	Description
role	string	yes	owner, admin, supervisor, agent or viewer (min length 1, max length 64)
teams	array of string		The store’s team ids the user is in; absent leaves the teams as they are (max 50 items)

UpdateWebhookEndpointInputBody

Field	Type	Required	Description
description	string		(max length 200)
events	array of string or null		(min 1 items, max 64 items)
status	"active" | "disabled"		active turns a disabled endpoint back on
url	string		(min length 8, max length 2048)

UpsertResultBody

Field	Type	Required	Description
externalId	string	yes
result	"created" | "updated" | "unchanged"	yes	unchanged: the product was the same, nothing is pushed to Meta

UseBody

Field	Type	Required	Description
digit	integer (int64)		The key of the IVR option
label	string	yes	Where it plays, in English
teamId	string (uuid)		The team whose settings play it; for an IVR option, the team the option routes to
teamName	string
type	"workspace_default" | "routing_greeting" | "ivr_option" | "team_hold" | "team_closed" | "team_missed" | "prayer_message" | "team_prayer"	yes

VariantBody

Field	Type	Required	Description
availability	"in_stock" | "out_of_stock"		The product’s when absent
color	string		(max length 100)
externalId	string	yes	The partner’s id for the variant, such as a size id; it is the WhatsApp retailer_id of the variant’s catalog item (min length 1, max length 100, pattern ^[A-Za-z0-9._:-]+$)
priceCents	integer (int64)		The variant’s own price in cents; the product’s when absent (min 0, max 100000000000)
salePriceCents	integer (int64)		The variant’s own sale price in cents; the product’s when absent (min 0, max 100000000000)
size	string		(max length 100)
stock	integer (int32)		The variant’s own stock; the product’s when absent. 0 shows it out of stock (min 0)

VariantViewBody

Field	Type	Required	Description
availability	"in_stock" | "out_of_stock"
color	string
externalId	string	yes	The WhatsApp retailer_id
priceCents	integer (int64)
salePriceCents	integer (int64)
size	string
stock	integer (int32)
sync	SyncBody	yes

WebhookDeliveriesOutputBody

Field	Type	Required	Description
deliveries	array of WebhookDeliveryBody	yes	Every attempt, the latest first
next	string		Pass as cursor for the next page; absent on the last page

WebhookDeliveryBody

Field	Type	Required	Description
attempt	integer (int64)	yes	1 for the first attempt of this delivery
attemptedAt	string (date-time)	yes
error	string		Why the attempt failed, when the response code does not say
eventId	string (uuid)	yes	The id in the delivered body; receivers dedupe on it
eventType	string	yes
id	string (uuid)	yes
latencyMs	integer (int64)	yes
nextRetryAt	string (date-time)		When the next attempt runs; absent after a success or the last attempt
responseCode	integer (int64)		Absent when no response arrived
status	"succeeded" | "failed"	yes
trigger	"event" | "replay" | "test"	yes

WebhookEndpointBody

Field	Type	Required	Description
createdAt	string (date-time)	yes
createdBy	string	yes	User id of who created the endpoint
description	string	yes
disabledAt	string (date-time)
disabledReason	"failing" | "manual"		failing: Nexafon turned it off after every delivery failed for 3 days
events	array of string	yes	Event types the endpoint receives
failingSince	string (date-time)		Deliveries have failed since then without a success
id	string (uuid)	yes
lastSuccessAt	string (date-time)
previousSecretExpiresAt	string (date-time)		After a rotation, deliveries are also signed with the previous secret until then
secretMasked	string	yes	The signing secret’s prefix and last four characters, such as whsec_…WXYZ
status	"active" | "disabled"	yes
updatedAt	string (date-time)	yes
url	string	yes

WebhookEndpointsOutputBody

Field	Type	Required	Description
endpoints	array of WebhookEndpointBody	yes

WebhookEventTypeBody

Field	Type	Required	Description
description	string	yes
emitted	boolean	yes	False while the module that sends it is not available yet; subscribing already is allowed
type	string	yes

WebhookEventTypesOutputBody

Field	Type	Required	Description
eventTypes	array of WebhookEventTypeBody	yes

WebhookSecretOutputBody

Field	Type	Required	Description
endpoint	WebhookEndpointBody	yes
secret	string		The signing secret. It is shown only in this response and cannot be retrieved again; a replay of the request for the same Idempotency-Key leaves it out.

WebhookTestOutputBody

Field	Type	Required	Description
eventId	string (uuid)	yes	The webhook.test event; its attempt shows in the delivery log