> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão Geral

> Gestão de canais (channels) do WhatsApp via /api/newsletter/*

**Auth:** `TokenAccount` ou `TokenInstance` em todas as rotas. Cada chamada valida a ownership da instância.

Esta seção cobre as rotas `/api/newsletter/*` para criar canais, listar inscrições, obter detalhes, seguir e deixar de seguir. Canais têm JIDs terminando em `@newsletter` (diferente de grupos `@g.us`).

## Endpoints

| Método | Path                               | Função                                             |
| ------ | ---------------------------------- | -------------------------------------------------- |
| POST   | `/api/newsletter/create/:instance` | [Criar canal](/pt/api/newsletter/create)           |
| GET    | `/api/newsletter/list/:instance`   | [Listar canais inscritos](/pt/api/newsletter/list) |
| GET    | `/api/newsletter/info/:instance`   | [Info de um canal](/pt/api/newsletter/info)        |
| POST   | `/api/newsletter/join/:instance`   | [Inscrever-se](/pt/api/newsletter/join)            |
| DELETE | `/api/newsletter/leave/:instance`  | [Cancelar inscrição](/pt/api/newsletter/leave)     |

## Identifiers aceitos

Os endpoints `info`, `join` e `leave` aceitam:

| Forma         | Exemplo                                           |
| ------------- | ------------------------------------------------- |
| JID           | `120363422585881117@newsletter`                   |
| Link completo | `https://whatsapp.com/channel/120363422585881117` |
| Código apenas | `120363422585881117`                              |

## Modelo `NewsletterChannel`

| Campo             | Tipo    | Descrição                                                          |
| ----------------- | ------- | ------------------------------------------------------------------ |
| `jid`             | string  | `<id>@newsletter`                                                  |
| `state`           | string  | `active`, `suspended`, `geosuspended`                              |
| `name`            | string  | Nome do canal                                                      |
| `description`     | string  | Pode ser vazia                                                     |
| `inviteLink`      | string? | `https://whatsapp.com/channel/<id>` (apenas para admins / criador) |
| `subscriberCount` | int     | Pode ser `0` se desconhecido                                       |
| `pictureUrl`      | string? | URL temporária do CDN do WhatsApp                                  |

## Estados de canal

| Estado         | Significado                                                       |
| -------------- | ----------------------------------------------------------------- |
| `active`       | Canal operacional, recebendo publicações e novos seguidores       |
| `suspended`    | Canal suspenso (violação de políticas), visível mas sem interação |
| `geosuspended` | Canal indisponível na sua região                                  |

## Envelope de erro

```json theme={null}
{
  "success": false,
  "error": { "message": "newsletter not found" }
}
```

## Suporte do cliente WhatsMeow

<Warning>
  Algumas rotas dependem de funções do cliente WhatsMeow que podem não estar disponíveis em determinadas builds. Quando isso acontece, o servidor retorna **HTTP 501** com mensagens específicas:

  * `WhatsApp client does not support newsletter creation`
  * `WhatsApp client does not support listing newsletters`
  * `WhatsApp client does not support FollowNewsletter`
  * `WhatsApp client does not support UnfollowNewsletter`
</Warning>

## Quadro de erros (resumo)

| HTTP | Mensagem                                                                             |
| ---- | ------------------------------------------------------------------------------------ |
| 400  | `The 'name' field is required`                                                       |
| 400  | `The 'identifier' query parameter is required (JID @newsletter or invite link/code)` |
| 400  | `Invalid newsletter identifier (use JID @newsletter or invite link/code)`            |
| 400  | `Instance is not connected to WhatsApp`                                              |
| 404  | `newsletter not found`                                                               |
| 500  | `failed to create newsletter: <reason>`                                              |
| 500  | `failed to follow newsletter: <reason>`                                              |
| 500  | `failed to leave newsletter: <reason>`                                               |
| 501  | `WhatsApp client does not support <method>`                                          |

## Próximo

<CardGroup cols={2}>
  <Card title="Criar canal" icon="bullhorn" href="/pt/api/newsletter/create">
    Cria um novo canal vinculado à conta.
  </Card>

  <Card title="Listar canais" icon="list" href="/pt/api/newsletter/list">
    Retorna canais inscritos.
  </Card>
</CardGroup>