Publicar status

POST/v1/instances/{id}/statusdesde M10token da instância ou admin

Quando usar

Publica um status (story) de texto, imagem ou vídeo. Os destinatários são os da privacidade do status configurada no celular (veja GET /status/privacy); o WhatsApp não permite escolher por envio. Passa pela fila de envio como POST /messages (ritmo, janela de horário, rampa, suspensão do operador, client_message_id, ?wait=true) e tem teto de 10 status por dia por instância (429 rate_limited). Texto: até 700 caracteres, background_color/text_color #RRGGBB e font 0, 1, 2, 6, 7, 8, 9 ou 10.

Autenticação

Aceita o token da instância (só a própria instância) ou o token admin. Um token de outra instância recebe 403 forbidden (ou 404 not_found em webhooks de outra instância).

Parâmetros

Caminho

Nome	Tipo	Descrição
`id`obrigatório	`string`	Id da instância (`inst_...`).

Query

Nome	Tipo	Descrição
`wait`	`boolean`	Espera o envio (até `timeout`, padrão 30s).
`timeout`	`string`

Corpo (JSON)

Nome	Tipo	Descrição
`type`obrigatório	`"text" \| "image" \| "video"`
`text`	`string`	text: o texto do status. (até 700)
`caption`	`string`	image/video: legenda.
`media`	`MediaInput`	Informe `url` ou `base64`.
`media.url`	`string`	http(s) público; o servidor baixa (timeout 30s, sem IPs privados).
`media.base64`	`string`
`media.mime`	`string`
`media.file_name`	`string`	Até 255 bytes.
`media.ptt`	`boolean`	Áudio como mensagem de voz.
`media.url`	`string`	http(s) público; o servidor baixa (timeout 30s, sem IPs privados).
`media.base64`	`string`
`media.mime`	`string`
`media.file_name`	`string`	Até 255 bytes.
`media.ptt`	`boolean`	Áudio como mensagem de voz.
`background_color`	`string`	text: cor de fundo #RRGGBB.
`text_color`	`string`
`font`	`0 \| 1 \| 2 \| 6 \| 7 \| 8 \| 9 \| 10`
`client_message_id`	`string`
`expires_after`	`string`

Exemplo

curl -s -X POST "$LITEZAP_URL/v1/instances/$ID/status" \
  -H "Authorization: Bearer $LITEZAP_TOKEN" \
  -d '{"type":"text","text":"Bom dia! Abrimos às 9h.","background_color":"#1E6E4F","font":1}'

const res = await fetch("http://localhost:8787/v1/instances/inst_7f3a9c2e5b1d4086/status", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.LITEZAP_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "type": "text",
    "text": "Bom dia! Abrimos às 9h.",
    "background_color": "#1E6E4F",
    "font": 1
  }),
});
console.log(res.status, res.status === 204 ? "" : await res.json());

import os
import requests

r = requests.post(
    "http://localhost:8787/v1/instances/inst_7f3a9c2e5b1d4086/status",
    headers={"Authorization": f"Bearer {os.environ['LITEZAP_TOKEN']}"},
    json={
        "type": "text",
        "text": "Bom dia! Abrimos às 9h.",
        "background_color": "#1E6E4F",
        "font": 1,
    },
    timeout=150,
)
print(r.status_code, r.json() if r.content else "")

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
  "strings"
)

func main() {
  req, _ := http.NewRequest("POST", "http://localhost:8787/v1/instances/inst_7f3a9c2e5b1d4086/status", strings.NewReader(`{"type":"text","text":"Bom dia! Abrimos às 9h.","background_color":"#1E6E4F","font":1}`))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("LITEZAP_TOKEN"))
  req.Header.Set("Content-Type", "application/json")
  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  out, _ := io.ReadAll(resp.Body)
  fmt.Println(resp.Status, string(out))
}

<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client(['base_uri' => 'http://localhost:8787']);
$res = $client->request('POST', '/v1/instances/inst_7f3a9c2e5b1d4086/status', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('LITEZAP_TOKEN')],
    'json' => [
        'type' => 'text',
        'text' => 'Bom dia! Abrimos às 9h.',
        'background_color' => '#1E6E4F',
        'font' => 1,
    ],
    'http_errors' => false,
]);
echo $res->getStatusCode(), ' ', $res->getBody(), PHP_EOL;

Outros corpos de exemplo

{
  "type": "image",
  "caption": "Novidade da semana",
  "media": {
    "url": "https://exemplo.com/foto.jpg"
  }
}

Nos exemplos, LITEZAP_URL é a URL base (ex.: http://localhost:8787) e o token vem deLITEZAP_TOKEN (instância) ou LITEZAP_ADMIN_TOKEN.

Resposta

200 Publicado (com ?wait=true).

Campos de Message

`id`	`string`
`client_message_id`	`string`
`wa_message_id`	`string`
`chat`	`string`
`sender`	`string`
`from_me`	`boolean`
`source`	`"contact" \| "api" \| "device" \| "history"`
`type`	`string`
`text`	`string`
`media`	`MediaInfo`
`media.id`	`string`	Id da mídia recebida.
`media.kind`	`string`
`media.mime`	`string`
`media.size`	`integer`
`media.file_name`	`string`
`media.seconds`	`integer`
`media.ptt`	`boolean`
`media.url`	`string`	Caminho da API para baixar (mídia recebida).
`reaction_to`	`string`
`status`	`"queued" \| "in_flight" \| "sent" \| "delivered" \| "read" \| "played" \| "failed" \| "received" \| "pending"`
`attempts`	`integer`
`error`	`string`	Último erro (`codigo: detalhe`) de item não enviado.
`timestamp`	`string`

{
  "id": "msg_5c1e9a7d3b2f4068",
  "wa_message_id": "3EB0C4D5E6F7A8B9C0D1E2",
  "chat": "status@broadcast",
  "from_me": true,
  "source": "api",
  "type": "text",
  "text": "Bom dia! Abrimos às 9h.",
  "status": "sent",
  "timestamp": "2026-10-18T12:00:03Z"
}

202 Na fila.

Campos de Message

`id`	`string`
`client_message_id`	`string`
`wa_message_id`	`string`
`chat`	`string`
`sender`	`string`
`from_me`	`boolean`
`source`	`"contact" \| "api" \| "device" \| "history"`
`type`	`string`
`text`	`string`
`media`	`MediaInfo`
`media.id`	`string`	Id da mídia recebida.
`media.kind`	`string`
`media.mime`	`string`
`media.size`	`integer`
`media.file_name`	`string`
`media.seconds`	`integer`
`media.ptt`	`boolean`
`media.url`	`string`	Caminho da API para baixar (mídia recebida).
`reaction_to`	`string`
`status`	`"queued" \| "in_flight" \| "sent" \| "delivered" \| "read" \| "played" \| "failed" \| "received" \| "pending"`
`attempts`	`integer`
`error`	`string`	Último erro (`codigo: detalhe`) de item não enviado.
`timestamp`	`string`

Erros

Código	HTTP	Retentável	O que fazer
`validation_failed`	400	não	Corrija o corpo ou os parâmetros; a `message` diz o campo.
`unauthorized`	401	não	Envie `Authorization: Bearer <token>` válido.
`forbidden`	403	não	Use o token certo (admin, ou o da própria instância).
`instance_not_found`	404	não	Confira o id da instância.
`conflict`	409	não	O recurso está num estado que não permite a operação; veja a `message`.
`instance_not_connected`	409	depende	Confira o estado da instância; se `logged_out`, pareie de novo.
`instance_banned`	409	não	Número banido: apague a instância.
`media_too_large`	413	não	Reduza o arquivo (imagem 16MB, vídeo/áudio 64MB, documento 100MB).
`media_fetch_failed`	422	sim	Confira se a URL é pública e responde; tente de novo.
`rate_limited`	429	sim	Espere e tente de novo com backoff.

Todo erro usa o envelope {"error":{"code","message","retryable"}}. Tabela completa em Erros.

Eventos gerados

Equivalente na Z-API: Enviar status de texto / imagem / vídeo. Veja Migrar da Z-API.

Outras operações de Status: Status recentes · Privacidade do status · Apagar status · Responder status