Inbox API

View as Markdown llms.txt

Generated from api/openapi.public.yaml, the same spec the API serves. Try these operations in the API console; errors are Problem Details.

List conversations

GET /api/v1/workspaces/{workspaceId}/conversations

Conversations of your teams, pinned first, then the latest first.


Operation id	`listConversations`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`inbox:reply`
Plan feature	`whatsapp.number`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)
`status`	query	`"active"` \| `"open"` \| `"snoozed"` \| `"closed"`		active: open and snoozed
`teamId`	query	string (uuid)		Only this team’s conversations
`assignee`	query	string		me, none, or a member id (UUID)
`cursor`	query	string		The next value of the previous page
`limit`	query	integer (int64)

Responses

Status	Description	Body
200	OK	`application/json`: ConversationListOutputBody
default	Error	`application/problem+json`: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/conversations" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"

Message a customer with a template

POST /api/v1/workspaces/{workspaceId}/conversations

Opens the customer’s conversation, or reuses it, and queues the template. Outside the 24-hour window WhatsApp allows only templates.


Operation id	`startConversation`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`inbox:reply`
Plan feature	`whatsapp.number`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)

Request body

application/json: 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

Responses

Status	Description	Body
202	Accepted	`application/json`: StartOutputBody
403	Forbidden	`application/problem+json`: Problem
404	Not Found	`application/problem+json`: Problem
409	Conflict	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem
503	Service Unavailable	`application/problem+json`: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/conversations" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":{"clientMsgId":"string","type":"text"},"phone":"string"}'

Get a conversation

GET /api/v1/workspaces/{workspaceId}/conversations/{conversationId}


Operation id	`getConversation`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`inbox:reply`
Plan feature	`whatsapp.number`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)
`conversationId`	path	string	yes	Conversation id (UUID)

Responses

Status	Description	Body
200	OK	`application/json`: ConversationBody
404	Not Found	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/conversations/{conversationId}" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"

List a conversation’s messages

GET /api/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages


Operation id	`listMessages`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`inbox:reply`
Plan feature	`whatsapp.number`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)
`conversationId`	path	string	yes	Conversation id (UUID)
`cursor`	query	string		The next value of the previous page
`limit`	query	integer (int64)

Responses

Status	Description	Body
200	OK	`application/json`: ThreadOutputBody
404	Not Found	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"

Send a message

POST /api/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages

Queues the message and returns it pending; status updates follow as message.updated events. Repeating clientMsgId returns the same message.


Operation id	`sendMessage`
Authentication	A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores.
Permission (key scope)	`inbox:reply`
Plan feature	`whatsapp.number`

Parameters

Name	In	Type	Required	Description
`workspaceId`	path	string	yes	Workspace id (UUID)
`conversationId`	path	string	yes	Conversation id (UUID)

Request body

application/json: 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

Responses

Status	Description	Body
202	Accepted	`application/json`: MessageBody
403	Forbidden	`application/problem+json`: Problem
404	Not Found	`application/problem+json`: Problem
409	Conflict	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem
503	Service Unavailable	`application/problem+json`: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clientMsgId":"string","type":"text"}'