# List messaging templates

> List your project's messaging templates, with their variables and where each can be sent now.

`GET https://api-connect.nxiom.com/api/v1/messaging/templates`

Use it to find the template to send and the values a send needs. Templates are created, submitted, and changed in the dashboard, under **Messaging → Templates**; see [Message templates](/docs/whatsapp/templates).

## Authorization

Requires `whatsapp.send`. A key with `whatsapp.full_access` can also list templates. WhatsApp must be turned on for your organization.

## Query parameters

| Field | Type | Description |
| --- | --- | --- |
| `status` | string · optional | `draft`, `submitted`, or `archived`. See [Drafts and submitted templates](/docs/whatsapp/templates#drafts-and-submitted-templates). |
| `content_type` | string · optional | `text`, `media`, `quick_reply`, `call_to_action`, `card`, `authentication`, or `carousel`. See [Content types](/docs/whatsapp/templates#content-types). |
| `category` | string · optional | `marketing`, `utility`, or `authentication`. |
| `language` | string · optional | Only templates in this exact language, such as `en` or `en_US`. |
| `channel` | string · optional | `whatsapp` or `sms`. Only templates whose content fits this channel. |
| `query` | string · optional | Part of the template name, 1 to 200 characters. Case doesn't matter. |

Unknown parameters are refused with `400`.

## Request

### cURL

```shell
curl "https://api-connect.nxiom.com/api/v1/messaging/templates?status=submitted&channel=whatsapp" \
  -H "Authorization: Bearer $NEXIOM_API_KEY"
```

### Node.js

```typescript
const apiKey = process.env.NEXIOM_API_KEY;
if (!apiKey) throw new Error('Set NEXIOM_API_KEY');

const response = await fetch(
  'https://api-connect.nxiom.com/api/v1/messaging/templates?status=submitted&channel=whatsapp',
  {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(result.message ?? `HTTP ${response.status}`);
}
console.log(result);
```

### PHP

```php
<?php

$apiKey = getenv('NEXIOM_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set NEXIOM_API_KEY');
}

$request = curl_init("https://api-connect.nxiom.com/api/v1/messaging/templates?status=submitted&channel=whatsapp");
curl_setopt_array($request, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey",
    ],
]);

$raw = curl_exec($request);
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);
$error = curl_error($request);
curl_close($request);

if ($raw === false) {
    throw new RuntimeException($error);
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($status >= 400) {
    throw new RuntimeException($result["message"] ?? "HTTP $status");
}
print_r($result);
```

## Response

HTTP `200`. Templates are under `data.items`, ordered by name, then language. The list isn't paginated. Deleted templates are never listed.

Each item is a [template object](/docs/api/messaging/templates/retrieve#the-template-object). A template can be sent on WhatsApp when `channel_status.whatsapp.ready` is `true`, from a number whose WhatsApp account has an approved [approval](/docs/api/messaging/templates/retrieve#whatsapp-approvals).

### 200 OK

Example response. Identifiers are illustrative.

```json
{
  "message": "Templates fetched",
  "data": {
    "items": [
      {
        "id": "mtp_example",
        "name": "order_confirmation",
        "language": "en",
        "category": "utility",
        "content_type": "quick_reply",
        "status": "submitted",
        "source": "library",
        "library_key": "order_confirmation",
        "content": {
          "header": null,
          "body": {
            "text": "Hello {{1}}, we received your order {{2}} for {{3}}. Please confirm it so we can prepare it for delivery.",
            "examples": { "1": "Amina", "2": "A-1234", "3": "4,500 DZD" }
          },
          "footer": null,
          "buttons": [
            { "type": "quick_reply", "text": "Confirm order" },
            { "type": "quick_reply", "text": "Cancel order" }
          ],
          "authentication": null,
          "cards": []
        },
        "variables": {
          "header": [],
          "body": ["1", "2", "3"],
          "header_media": null,
          "buttons": [
            { "index": 0, "type": "quick_reply", "required": false },
            { "index": 1, "type": "quick_reply", "required": false }
          ],
          "code": false,
          "cards": []
        },
        "channels": ["whatsapp"],
        "channel_status": {
          "whatsapp": {
            "ready": true,
            "approvals": [
              {
                "whatsapp_template_id": "wat_example",
                "account_id": "wac_example",
                "waba_id": "100000000000001",
                "status": "active",
                "approval_status": "approved",
                "category": "utility",
                "rejection_reason": null,
                "unsupported_reason": null,
                "matches_content": true,
                "submitted_at": "2026-10-17T08:00:00.000Z",
                "last_synced_at": "2026-10-17T08:05:00.000Z"
              }
            ]
          },
          "sms": { "ready": false }
        },
        "unsupported_reason": null,
        "duplicated_from_id": null,
        "submitted_at": "2026-10-17T08:00:00.000Z",
        "archived_at": null,
        "created_at": "2026-10-17T07:50:00.000Z",
        "updated_at": "2026-10-17T08:00:00.000Z"
      }
    ]
  }
}
```

### 400 Bad Request

The request is invalid. Correct it before retrying; `details` lists the failing fields.

```json
{
  "error": "invalid_argument",
  "message": "Request doesn't match the schema",
  "correlationId": "req_example",
  "details": {
    "context": "body",
    "issues": []
  }
}
```

### 401 Unauthorized

The API key is missing, malformed, revoked, or expired.

```json
{
  "error": "unauthorized",
  "message": "Invalid API key",
  "correlationId": "req_example"
}
```

### 403 Forbidden

The API key lacks whatsapp.send, or WhatsApp is not turned on for your organization (code: FEATURE_NOT_AVAILABLE).

```json
{
  "error": "not_allowed",
  "message": "Missing required API key permissions: whatsapp.send",
  "correlationId": "req_example"
}
```

---

Source: https://connect.nxiom.com/docs/api/messaging/templates/list