Templates 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 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
default	Error	`application/problem+json`: Problem

Example

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

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_]+$`)

Responses

Status	Description	Body
202	Accepted	`application/json`: TemplateBody
409	Conflict	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

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
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}/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

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

Responses

Status	Description	Body
202	Accepted	`application/json`: TemplateBody
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

Example

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

Example

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

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

Responses

Status	Description	Body
200	OK	`application/json`: PreviewOutputBody
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 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
409	Conflict	`application/problem+json`: Problem
422	Unprocessable Entity	`application/problem+json`: Problem
500	Internal Server Error	`application/problem+json`: Problem

Example

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