# Templates

## Endpoints

- `POST /graph/whatsapp/{version}/{wabaId}/message_templates`: [Create message template](https://docs.polymorfa.com/api/graph/templates/create-message-template)
- `GET /graph/whatsapp/{version}/{wabaId}/message_templates`: [List message templates](https://docs.polymorfa.com/api/graph/templates/list-message-templates)
- `DELETE /graph/whatsapp/{version}/{wabaId}/message_templates`: [Delete message template](https://docs.polymorfa.com/api/graph/templates/delete-message-template)

## The message template object

### Attributes

- `id` (string, required). Identifier for this resource.
- `name` (string, required). Human-readable name for this resource.
- `language` (string, required). Language or locale code used for this content.
- `category` (string, required). Specifies category for this graph graph message template.
- `status` (string, required). Current status of this resource or operation.
- `components` (array of any, required, nullable items). Structured components that make up this message or template.
- `quality_score` (object). Structured quality score values for this graph graph message template.
  - `score` (string, required). Specifies score for this quality score.
- `rejected_reason` (string, nullable). Specifies rejected reason for this graph graph message template.
- `previous_category` (string, nullable). Specifies previous category for this graph graph message template.
```json
{
  "id": "string",
  "name": "string",
  "language": "string",
  "category": "string",
  "status": "string",
  "components": [
    null
  ],
  "quality_score": {
    "score": "string"
  },
  "rejected_reason": "string",
  "previous_category": "string"
}
```

## Create message template

`POST https://api.polymorfa.com/graph/whatsapp/{version}/{wabaId}/message_templates` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `wabaId` (string, required). Identifier for the waba.

### Header parameters

- `Idempotency-Key` (string, min length 1). Optional key of 1 to 255 UTF-8 bytes, retained for 24 hours. Reuse it for the same request after an uncertain outcome; a completed request is not sent again.

### Body

- `name` (string, required). Human-readable name for this resource.
- `language` (string, required). Language or locale code used for this content.
- `category` (string, required). Specifies category for this graph graph create message template request. Values: `UTILITY`, `MARKETING`, `AUTHENTICATION`.
- `allow_category_change` (boolean). Whether allow category change.
- `components` (array of any, required, max items 1000, nullable items). Structured components that make up this message or template.

### Request

```bash
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/<wabaId>/message_templates" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "order_update",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    null
  ]
}'
```

### Responses

#### 200

Template submitted
- `id` (string, required). Identifier for this resource.
- `status` (string, required). Current status of this resource or operation.
- `category` (string, required). Specifies category for this graph graph create message template response.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "id": "string",
  "status": "string",
  "category": "string"
}
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 409

Idempotency key completed, in progress, has an unknown outcome, or was reused for a different request
Same fields as 400.

Headers:

- `X-Polymorfa-Error-Code` (string). Stable idempotency error code
- `Idempotent-Replayed` (string). true for a recorded outcome
- `Retry-After` (integer, min 0). Seconds before checking an in-progress request again
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 502

Provider response unavailable or malformed; the write outcome may be unknown
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 503

Provider unavailable or pre-dispatch reservation failed; use the stable error code to distinguish an unknown outcome from a proven no-attempt refusal
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## List message templates

`GET https://api.polymorfa.com/graph/whatsapp/{version}/{wabaId}/message_templates` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `wabaId` (string, required). Identifier for the waba.

### Request

```bash
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/<wabaId>/message_templates" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>"
```

### Responses

#### 200

Message templates
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string, required). Identifier for this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `language` (string, required). Language or locale code used for this content.
  - `category` (string, required). Specifies category for this graph graph message template.
  - `status` (string, required). Current status of this resource or operation.
  - `components` (array of any, required, nullable items). Structured components that make up this message or template.
  - `quality_score` (object). Structured quality score values for this graph graph message template.
    - `score` (string, required). Specifies score for this quality score.
  - `rejected_reason` (string, nullable). Specifies rejected reason for this graph graph message template.
  - `previous_category` (string, nullable). Specifies previous category for this graph graph message template.
- `paging` (object, required). Structured paging values for this graph graph message templates list response.
  - `cursors` (object, required). Structured cursors values for this paging.
    - `before` (string). Specifies before for this cursor.
    - `after` (string). Specifies after for this cursor.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "language": "string",
      "category": "string",
      "status": "string",
      "components": [
        null
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "string",
      "after": "string"
    }
  }
}
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## Delete message template

`DELETE https://api.polymorfa.com/graph/whatsapp/{version}/{wabaId}/message_templates` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

A successful response confirms provider deletion. A later complete catalog read reconciles any stored template copies that could not be removed during the delete request.

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `wabaId` (string, required). Identifier for the waba.

### Query parameters

- `name` (string). Human-readable name for this resource.

### Header parameters

- `Idempotency-Key` (string, min length 1). Optional key of 1 to 255 UTF-8 bytes, retained for 24 hours. Reuse it for the same request after an uncertain outcome; a completed request is not sent again.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/graph/whatsapp/v26.0/<wabaId>/message_templates" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>"
```

### Responses

#### 200

Deleted
- `success` (boolean, required). Whether the request succeeded.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true
}
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 409

Idempotency key completed, in progress, has an unknown outcome, or was reused for a different request
Same fields as 400.

Headers:

- `X-Polymorfa-Error-Code` (string). Stable idempotency error code
- `Idempotent-Replayed` (string). true for a recorded outcome
- `Retry-After` (integer, min 0). Seconds before checking an in-progress request again
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 502

Provider response unavailable or malformed; the write outcome may be unknown
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 503

Provider unavailable or pre-dispatch reservation failed; use the stable error code to distinguish an unknown outcome from a proven no-attempt refusal
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```
