# Templates API

> Reference for the 7 public v1 operations of the Templates API, generated from the OpenAPI spec.

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

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 WhatsApp templates

`GET /api/v1/workspaces/{workspaceId}/templates`

The templates of the workspace's WhatsApp Business Account, as Meta last reported them.

| | |
| --- | --- |
| Operation id | `listTemplates` |
| 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) | `templates:send` |
| Plan feature | `whatsapp.number` |

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | string | yes | Workspace id (UUID) |
| `status` | query | `"submitting"` \| `"submit_failed"` \| `"pending"` \| `"approved"` \| `"rejected"` \| `"paused"` \| `"disabled"` \| `"in_appeal"` \| `"pending_deletion"` \| `"limit_exceeded"` \| `"archived"` \| `"deleting"` |  | Only templates with this status, such as approved for the send picker |
| `category` | query | `"marketing"` \| `"utility"` \| `"authentication"` |  |  |
| `prefix` | query | string |  | Only names starting with this |
| `cursor` | query | string |  | The next value of the previous page |
| `limit` | query | integer (int64) |  |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | `application/json`: [ListOutputBody3](/v1/api/schemas/#listoutputbody3) |
| default | Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

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

## Submit a new WhatsApp template

`POST /api/v1/workspaces/{workspaceId}/templates`

Checks the template against Meta's rules, then queues it for Meta's review: it starts as submitting, and template.updated events follow as Meta reviews it.

| | |
| --- | --- |
| Operation id | `createTemplate` |
| 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) | `templates:manage` |
| Plan feature | `whatsapp.number` |

### Parameters

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

### Request body

`application/json`: [CreateInputBody2](/v1/api/schemas/#createinputbody2)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `category` | `"marketing"` \| `"utility"` \| `"authentication"` | yes |  |
| `definition` | [TemplateDefinitionBody](/v1/api/schemas/#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_]+$`) |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 202 | Accepted | `application/json`: [TemplateBody](/v1/api/schemas/#templatebody) |
| 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) |

### Example

```bash
curl -X POST "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/templates" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"marketing","definition":{"body":null},"language":"string","name":"string"}'
```

## Get a WhatsApp template with its usage

`GET /api/v1/workspaces/{workspaceId}/templates/{templateId}`

| | |
| --- | --- |
| Operation id | `getTemplate` |
| 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) | `templates:send` |
| Plan feature | `whatsapp.number` |

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | string | yes | Workspace id (UUID) |
| `templateId` | path | string | yes | Template id (UUID) |
| `since` | query | string (date-time) |  | Count usage from this time; the last 30 days by default |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | `application/json`: [TemplateBody](/v1/api/schemas/#templatebody) |
| 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}/templates/{templateId}" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"
```

## Edit a WhatsApp template

`PUT /api/v1/workspaces/{workspaceId}/templates/{templateId}`

Approved, rejected and paused templates go back to Meta's review; a template Meta refused to create is submitted again.

| | |
| --- | --- |
| Operation id | `editTemplate` |
| 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) | `templates:manage` |
| Plan feature | `whatsapp.number` |

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | string | yes | Workspace id (UUID) |
| `templateId` | path | string | yes | Template id (UUID) |

### Request body

`application/json`: [EditInputBody](/v1/api/schemas/#editinputbody)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `category` | `"marketing"` \| `"utility"` |  | Unchanged when absent |
| `definition` | [TemplateDefinitionBody](/v1/api/schemas/#templatedefinitionbody) | yes |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 202 | Accepted | `application/json`: [TemplateBody](/v1/api/schemas/#templatebody) |
| 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) |

### Example

```bash
curl -X PUT "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/templates/{templateId}" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"definition":{"body":null}}'
```

## Delete a WhatsApp template

`DELETE /api/v1/workspaces/{workspaceId}/templates/{templateId}`

Deletes this language of the template at Meta; a template.deleted event follows.

| | |
| --- | --- |
| Operation id | `deleteTemplate` |
| 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) | `templates:manage` |
| Plan feature | `whatsapp.number` |

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | string | yes | Workspace id (UUID) |
| `templateId` | path | string | yes | Template id (UUID) |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 202 | Accepted | `application/json`: [TemplateBody](/v1/api/schemas/#templatebody) |
| 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) |

### Example

```bash
curl -X DELETE "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/templates/{templateId}" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"
```

## Preview a template with parameters

`POST /api/v1/workspaces/{workspaceId}/templates/{templateId}/preview`

Checks the parameters exactly as sending does, and returns the message the customer will see. Invalid parameters get 422 with the field of each problem.

| | |
| --- | --- |
| Operation id | `previewTemplate` |
| 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) | `templates:send` |
| Plan feature | `whatsapp.number` |

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | string | yes | Workspace id (UUID) |
| `templateId` | path | string | yes | Template id (UUID) |

### Request body

`application/json`: [PreviewInputBody](/v1/api/schemas/#previewinputbody)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `components` | array of [TemplateComponentBody](/v1/api/schemas/#templatecomponentbody) |  | The parameters, exactly as sending the template takes them (max 12 items) |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | `application/json`: [PreviewOutputBody](/v1/api/schemas/#previewoutputbody) |
| 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 POST "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/templates/{templateId}/preview" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Sync templates from Meta

`POST /api/v1/workspaces/{workspaceId}/templates/sync`

Queues a read of every template from Meta; only templates that changed are written. A template.synced event follows.

| | |
| --- | --- |
| Operation id | `syncTemplates` |
| 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) | `templates:manage` |
| Plan feature | `whatsapp.number` |

### Parameters

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

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 202 | Accepted | `application/json`: [SyncOutputBody](/v1/api/schemas/#syncoutputbody) |
| 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) |

### Example

```bash
curl -X POST "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/templates/sync" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"
```