# Inbox API

> Reference for the 5 public v1 operations of the Inbox API, generated from the OpenAPI spec.

Source: https://docs.nexafone.so/v1/api/inbox/

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

## 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](/v1/api/schemas/#conversationlistoutputbody) |
| default | Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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](/v1/api/schemas/#startinputbody)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | [SendBody](/v1/api/schemas/#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](/v1/api/schemas/#startoutputbody) |
| 403 | Forbidden | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 404 | Not Found | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 409 | Conflict | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 503 | Service Unavailable | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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](/v1/api/schemas/#conversationbody) |
| 404 | Not Found | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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](/v1/api/schemas/#threadoutputbody) |
| 404 | Not Found | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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](/v1/api/schemas/#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](/v1/api/schemas/#mediasendbody) |  |  |
| `replyToMessageId` | string (uuid) |  | Quote this message |
| `template` | [TemplateSendBody](/v1/api/schemas/#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](/v1/api/schemas/#messagebody) |
| 403 | Forbidden | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 404 | Not Found | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 409 | Conflict | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 503 | Service Unavailable | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
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"}'
```