Como o limite de 500 caracteres da API do Threads trata a topic_tag

A que se aplica o limite de 500 caracteres da API do Threads?

A Meta restringe o limite de 500 caracteres da API do Threads ao parâmetro text de um contêiner de mídia, e mantém a topic_tag como um parâmetro separado com teto próprio de 50 caracteres. O teto aparece como um item de uma linha sob Limitations na seção Single Thread Posts: "Text posts are limited to 500 characters." A página de visão geral do Threads repete a mesma frase palavra por palavra sob Other Limitations.

Nenhuma das duas páginas liga um nome de campo a essa frase. O endpoint de contêiner aceita text nos tipos de mídia TEXT, IMAGE, VIDEO e CAROUSEL, e o item dos 500 fica sob um título sobre posts de texto, então a Meta deixa em aberto se uma legenda em um post de imagem ganha o mesmo teto. Nenhum segundo número aparece em qualquer lugar da documentação do Threads, o que faz dos 500 o único teto com que uma integração pode contar para qualquer valor de text.

A regra de contagem anexada a esse item é a parte que a maioria dos contadores de caracteres erra: "Emojis are counted as the number of UTF-8 bytes." Um emoji de família de quatro pessoas custa 25 dos 500 em vez de 1, o que está coberto por inteiro em por que o limite de caracteres do Threads conta emoji como bytes UTF-8.

A topic_tag conta contra os 500?

A Meta não diz. O parâmetro topic_tag é documentado em uma subseção própria com sua própria restrição, "Topic tags must be at least 1 character and no more than 50 characters long", e nada no guia de posts nem na referência de publicação amarra esse valor ao limite de caracteres do post.

O que a documentação estabelece é onde cada coisa vive. A topic_tag é um campo de formulário separado em POST /{threads-user-id}/threads, enviado ao lado do text:

curl -i -X POST \
  -d "media_type=TEXT" \
  -d "text=<TEXT>" \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "topic_tag=<TAG>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Uma tag dentro do texto é o caso oposto e não precisa de nenhuma decisão da Meta, porque a tag faz parte da string que você põe no text. Todo caractere de #socialmedia é um caractere do post, então uma tag dentro do texto gasta os 500 por construção. Essa assimetria é a razão prática para preferir o parâmetro: o caminho dentro do texto é uma cobrança documentada contra os 500, e o caminho do parâmetro é uma questão em aberto.

Qual é a diferença entre topic_tag e uma tag dentro do texto?

A Meta aceita as duas e marca uma delas como legado. O método dentro do texto carrega um aviso explícito na documentação: "This method is not preferred but is kept for backwards compatability."

Uma regra vale para os dois caminhos: "Only one topic tag is allowed per post, so the first valid tag included in a post of any type (text-only, image, video, carousel) via the API is treated as the tag for that post." Palavras extras com cerquilha no corpo não viram tópicos extras, e mesmo assim custam caracteres.

As duas páginas de documentação também discordam em quanto contam. O guia de posts declara a faixa de 1 a 50 caracteres para topic tags. A referência de POST /{threads-user-id}/threads lista a topic_tag apenas com os caracteres proibidos e nenhuma regra de tamanho, então quem lê só a referência nunca vê os 50.

Quais caracteres são proibidos em uma topic tag do Threads?

Os dois caminhos têm listas de proibições diferentes, e a lista da tag dentro do texto é bem mais longa. Para o parâmetro, a Meta proíbe dois caracteres: pontos e e comerciais. Para uma tag dentro do texto, a Meta diz que "any in-text tag that starts with a hash sign will end just before these characters" e então dá o conjunto completo.

Uma regra separada mata as tags numéricas: "Whole numbers that are preceded by a hash sign (i.e., #1) will not be converted into a tag. This is because it is assumed that # is signifying a number sign in this scenario." A Meta também observa que "The text is also configured in the app without the hash sign", ou seja, a cerquilha é marcação para a API e não parte do tópico.

A consequência prática é um corte silencioso. Escrever #social media no text produz o tópico "social" e deixa a palavra "media" como texto puro, sem erro e sem aviso. Enviar social media como topic_tag preserva a frase inteira.

Que outros campos de texto a API do Threads limita?

Quatro limites diferentes governam o que entra em um post do Threads, e só um deles é o dos 500. Confundi-los é a causa habitual de um contêiner que falha na criação por motivos que o contador de caracteres nunca previu.

A regra dos links é a única com uma string de falha documentada. A partir de 22 de dezembro de 2025, a Meta afirma que "Threads posts containing more than 5 links will fail to post during the media creation step (POST /{threads-user-id}/threads) with the error code: THREADS_API__LINK_LIMIT_EXCEEDED." Os links são contados após a deduplicação: uma URL repetida no text conta uma vez, e um link_attachment que coincide com uma URL já presente no text "is only counted once, rather than twice".

Nada comparável existe para os 500. O índice da Threads API Reference não traz página de códigos de erro, e a página de troubleshooting documenta apenas valores de status de contêiner e valores de error_message de vídeo, então um text acima do limite não tem nenhuma constante de erro publicada para ser capturada.

O que acontece se o text passar de 500?

A Meta documenta o limite e não a resposta, então a única jogada confiável é medir antes de enviar. Como emoji são contados como bytes UTF-8 e não como caracteres, a medição tem de ser feita sobre a string codificada. Um String.length de 475 em JavaScript pode ser 517 bytes depois de alguns emoji, que é exatamente o modo de falha descrito em a página do limite de caracteres do Threads.

A mesma questão de contagem de bytes aparece em toda rede que guarda o texto do post em UTF-8, incluindo o jeito como os facets do Bluesky indexam links por byteStart e byteEnd em vez de por posição de caractere. Qualquer integração que publique em mais de uma rede precisa de um contador correto em bytes, e não de um por plataforma.

O que isso significa para posts agendados no Threads?

Um agendador monta o contêiner muito antes da chamada de publicação, então os 500 têm de ser aplicados no momento do rascunho e não no do envio. Duas verificações cobrem a maior parte: contar o text em bytes UTF-8 e mover tópicos para a topic_tag em vez de para o corpo quando o post está perto do teto.

A restrição do lado da publicação é outra, já que o Threads também limita um perfil a 250 posts publicados pela API dentro de um período móvel de 24 horas. Limites de caractere rejeitam um contêiner na criação, e limites de cota o rejeitam na publicação, que são duas falhas diferentes para projetar em volta. Para times que planejam o Threads junto de outras redes, a página da ferramenta de agendamento para Threads explica como a AdaptlyPost conecta pela API oficial.

Perguntas frequentes

O limite de 500 caracteres da API do Threads é o mesmo do app do Threads?

O número 500 que a Meta publica para a API bate com o que o Threads mostra no próprio compositor, e a Meta documenta a regra de emoji contado em bytes apenas na documentação da API. As páginas da API são as que enunciam a regra com precisão, então trate-as como a especificação para qualquer coisa que você construir.

Um post do Threads pode ter mais de uma topic tag?

Não. A Meta afirma que "Only one topic tag is allowed per post", e que a primeira tag válida em um post de qualquer tipo é a que vale. Palavras adicionais com cerquilha continuam sendo texto puro dentro do text e ainda contam para os 500.

A cerquilha conta como caractere em uma tag dentro do texto?

Uma tag dentro do texto vive dentro do valor de text, então cada caractere dela conta, cerquilha inclusive. A Meta observa que o tópico em si é guardado sem a cerquilha: "The text is also configured in the app without the hash sign."

Por que minha topic tag é cortada no meio?

Uma tag dentro do texto termina no primeiro caractere da lista de proibidos da Meta, que inclui espaços, pontos, e comerciais, arrobas, pontos de exclamação, pontos de interrogação, vírgulas, ponto e vírgulas e dois-pontos. Um tópico de várias palavras escrito no corpo vira, portanto, uma tag de uma palavra só. Mande-o pelo parâmetro topic_tag, onde espaços não estão na lista de proibidos.

Qual é o tamanho máximo do texto alternativo no Threads?

1.000 caracteres. A Meta declara o número na referência de POST /{threads-user-id}/threads: "The maximum length of alt_text is 1.000 characters." Esse orçamento é separado dos 500 do text.

Onde a Meta documenta o limite de 500 caracteres?

Em dois lugares, com redação idêntica. O guia de posts em developers.facebook.com/documentation/threads/posts traz "Text posts are limited to 500 characters." sob Limitations na seção Single Thread Posts, e a página de visão geral em developers.facebook.com/documentation/threads/overview repete o mesmo sob Other Limitations. A regra de contagem de emoji em bytes aparece ao lado dela no guia de posts.

A topic_tag é contada em bytes UTF-8 assim como text?

A Meta enuncia a regra de bytes UTF-8 só para o campo text, ligada ao limite de 500. A seção de topic_tag traz um intervalo de 1 a 50 caracteres sem citar bytes, então não está documentado se uma tag carregada de emoji conta em bytes ou em caracteres. Até a Meta dizer o contrário, vale tratar esse 50 como caracteres, a unidade que a documentação de fato usa.

O que acontece se um post do Threads tiver mais de 5 links?

O container falha na criação. A Meta indica que o erro chega na etapa de criação da mídia, POST /{threads-user-id}/threads, com o código THREADS_API__LINK_LIMIT_EXCEEDED. É o único limite da página com uma string de erro documentada, diferente dos 500 em text.

Um link repetido conta duas vezes para o limite de 5?

Conta uma vez só. A Meta conta os links depois de remover duplicados, então a mesma URL repetida em text conta como um link, e um link_attachment que coincide com uma URL já presente em text "só é contado uma vez, não duas". Cinco links únicos continuam sendo o teto.

A topic_tag funciona em um post de imagem ou vídeo, não só em um post de texto puro?

Sim, a regra vale para todo tipo de mídia. A Meta diz que a primeira tag válida em "a post of any type (text-only, image, video, carousel)" se torna a tag daquele post, então a topic_tag funciona do mesmo jeito, seja o container uma imagem, um vídeo ou um carrossel.