A StackZap documenta endpoints separados para imagem, áudio e documento. As operações recebem dados da instância e do destinatário, além de uma URL acessível para a mídia. Antes de integrar, confirme os campos suportados na versão que está usando e as cotas do seu plano Cloud.

Estrutura da chamada

A referência técnica usa payload JSON com to e url. Dependendo do tipo e do endpoint, também pode aceitar caption, mime_type e filename. O servidor busca o conteúdo pelo endereço informado, então a URL precisa ser acessível para o ambiente StackZap e retornar um arquivo válido.

curl -X POST "$STACKZAP_API_URL/v1/instances/$STACKZAP_INSTANCE_ID/messages/image" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $STACKZAP_API_KEY" \
  -d '{"to":"[email protected]","url":"https://seu-dominio.example/imagem.jpg","caption":"Material solicitado"}'

Para áudio ou documento, use o endpoint do tipo correspondente. O corpo aceito pode variar: consulte o schema de cada operação na referência da API antes de implantar.

Checklist para uma mídia acessível

  • A URL usa HTTPS e não depende de login ou cookie de navegador.
  • O endereço retorna o arquivo diretamente, sem uma página HTML intermediária.
  • O arquivo não está vazio e o tipo informado combina com seu conteúdo.
  • A legenda e o nome do arquivo não incluem dados que você não queira expor ao destinatário.
  • O volume e quantidade de uploads respeitam os limites mostrados no plano Cloud.

Escolha o formato conforme a tarefa

O envio de mídia deve resolver uma necessidade concreta da conversa. Uma imagem pode ilustrar um produto ou comprovante; um documento pode apresentar um arquivo que a pessoa espera receber; um áudio pode transmitir uma orientação falada. Não use mídia apenas para contornar uma mensagem de texto longa ou para tornar uma comunicação inesperada mais chamativa. Diga o que o arquivo contém e por que ele foi enviado.

Confira na documentação da sua versão quais tipos de mídia, limites, parâmetros e formatos são aceitos. A API pode receber uma URL acessível, conteúdo codificado ou outra forma definida pelo endpoint. Os detalhes não são intercambiáveis: se o servidor espera uma URL, mandar o caminho local do seu computador não permitirá que ele acesse o arquivo. Também não presuma que o nome, MIME type ou legenda sejam opcionais sem conferir a referência.

Na StackZap Cloud, considere as cotas de armazenamento e transferência do plano. O volume diário enviado e o espaço para mídias são medidas diferentes. Remover ou organizar arquivos armazenados pode ser necessário para seu fluxo, mas não confunda backup com consumo de cota diária. Consulte a página de planos para confirmar valores atuais.

Prepare o arquivo com segurança

Antes do upload, valide o tamanho, extensão e tipo real do arquivo. A extensão do nome pode não corresponder ao conteúdo. Defina um limite no seu aplicativo e rejeite formatos inesperados. Remova metadados desnecessários de imagens quando isso fizer sentido, evite arquivos executáveis e aplique antivírus ou varredura apropriada ao perfil do sistema que recebe uploads.

Armazene o arquivo em uma origem que a API consiga buscar, com acesso temporário se a documentação suportar URLs assinadas. Não use um link público permanente para documentos privados. Certifique-se de que a validade do link cobre o tempo necessário para processamento. Teste a leitura da URL a partir da infraestrutura que fará a requisição, pois um link acessível no navegador da sua máquina pode depender de uma sessão ou cookie que o servidor da StackZap não tem.

Use nomes de arquivo neutros, sem CPF, telefone ou outros dados pessoais. Evite colocar informação confidencial em URL, que pode aparecer em logs. Se o arquivo contiver dados de cliente, limite o acesso e retenha-o apenas pelo tempo necessário. As regras de privacidade da sua aplicação continuam valendo quando um arquivo passa pela API.

Exemplo ilustrativo de requisição

A API de mensagens de mídia documenta campos como destinatário, URL, legenda, tipo MIME e nome de arquivo. O trecho ilustra a composição; confirme o endpoint e os campos exigidos na documentação técnica da versão:

{
  "to": "5521999999999",
  "url": "https://arquivos.exemplo.com/arquivo-temporario",
  "caption": "Documento solicitado no atendimento",
  "mimeType": "application/pdf",
  "fileName": "documento.pdf"
}

Use um domínio e arquivo de teste sob seu controle; arquivos.exemplo.com é apenas ilustrativo. Envie primeiro para um número autorizado da equipe e confira no aparelho se o documento abriu corretamente, se o nome está claro e se a legenda corresponde ao conteúdo. Um status HTTP sem erro não substitui a validação do resultado final no fluxo real.

URL acessível não significa arquivo seguro

Se o endpoint recebe URL, valide o domínio antes de montar a requisição. Não permita que uma pessoa envie qualquer endereço para o backend buscar sem controle: isso pode expor recursos internos ou gerar acesso indevido a dados. Restrinja destinos a um bucket ou serviço aprovado, valide esquema HTTPS e bloqueie endereços privados conforme a arquitetura. Essa proteção é especialmente relevante quando uma automação recebe instruções de terceiros.

Configure a validade de links de acordo com o tempo de processamento e não compartilhe URL assinada em ferramentas públicas. Se a transferência falhar, confira validade, permissões, redirects e resposta do servidor de arquivos. Não deixe URLs temporárias em logs por mais tempo do que o necessário.

Legenda, MIME type e nome do arquivo

O MIME type deve descrever o conteúdo real e seguir o formato esperado pela API. Um valor incorreto pode fazer o destinatário não conseguir abrir o arquivo ou mostrar uma experiência confusa. O nome de arquivo deve ser curto, reconhecível e sem caracteres problemáticos para dispositivos diferentes. Uma legenda contextualiza a mídia; ela não deve substituir informações importantes que o destinatário precisa compreender mesmo se o arquivo não carregar.

Para imagens, avalie resolução, orientação e tamanho. Para áudio, confira duração e se o formato é compatível com os clientes que seus destinatários usam. Para documentos, abra o arquivo em leitores comuns, confirme que não está corrompido e teste a apresentação do nome. Esses passos reduzem chamadas de suporte causadas por arquivos em branco, ilegíveis ou trocados.

Falhas e repetição segura

Trate erros de validação localmente antes de chamar a API. Se o arquivo exceder o limite conhecido, explique ao operador qual limite deve ser respeitado e não envie a chamada. Se houver erro de autenticação, corrija a credencial; repetir a mesma requisição não resolverá. Se a instância estiver desconectada, interrompa o envio e aguarde a reconexão antes de processar novas mídias.

Um timeout pode acontecer depois de a requisição ter sido aceita. Antes de tentar novamente, consulte a resposta armazenada pela aplicação, o identificador de mensagem e os webhooks disponíveis. Se não existir confirmação conclusiva, marque o resultado como incerto e encaminhe para uma regra de reconciliação. O envio duplicado de um documento ou áudio pode confundir ou expor dados em duplicidade.

Cuide das cotas e da retenção

Armazenamento, tráfego diário e limite de operações são conceitos distintos. Confira a página de planos da StackZap Cloud para saber os valores em vigor e implemente métricas próprias para tamanho e frequência de upload. Uma rotina de limpeza deve respeitar requisitos legais e de negócio; não remova automaticamente arquivos necessários para auditoria ou atendimento sem política definida.

Backups não consomem a cota diária de envio conforme a definição comercial informada, e a renovação da cota não apaga por si só os dados já armazenados. Ainda assim, não infira prazo de retenção nem disponibilidade indefinida de arquivos sem uma política documentada. Consulte os termos e a equipe de suporte para esclarecer dúvidas sobre retenção específica.

Checklist antes de enviar mídia

  • O destinatário espera receber o arquivo e está correto.
  • O arquivo está íntegro, é do tipo permitido e respeita os limites.
  • A URL é acessível pela infraestrutura e não expõe conteúdo público indevido.
  • MIME type, nome e legenda descrevem o arquivo corretamente.
  • A chave da API fica no backend e não é registrada em logs.
  • Cotas e espaço foram verificados para o volume esperado.
  • A integração trata timeout e evita repetição sem reconciliação.
  • A política de retenção cobre a cópia mantida pelo seu sistema.

Considere a experiência de quem recebe

Avise que o arquivo está chegando e descreva o que fazer com ele. Uma mídia sem legenda pode parecer inesperada, enquanto um documento com nome genérico como arquivo1.pdf é difícil de identificar. Use linguagem clara, evite anexar várias versões e mantenha o conteúdo coerente com o pedido que originou o envio.

Teste a abertura em dispositivos diferentes e em conexões móveis. Uma imagem muito grande pode demorar ou consumir dados; prefira tamanho adequado à finalidade. Não comprima a ponto de tornar comprovantes ilegíveis. Para documentos, valide páginas, orientação, senha e se o arquivo não contém páginas de outra pessoa.

Controle arquivos temporários

Se seu sistema cria URLs assinadas, registre a expiração e evite que o worker tente usá-las depois do prazo. Se o envio falhar por URL expirada, gere um link novo somente depois de verificar se a solicitação continua válida. Não deixe arquivos temporários acessíveis sem autenticação por tempo indeterminado.

Armazene o status da transferência sem guardar uma cópia extra do conteúdo no log. Se uma mensagem não for aceita, preserve o arquivo em local seguro até decidir se deve tentar de novo; se não for mais necessário, remova conforme sua política. Evite sincronizar anexos para dispositivos pessoais de operadores sem razão aprovada.

Considere a experiência de quem recebe

Avise que o arquivo está chegando e descreva o que fazer com ele. Uma mídia sem legenda pode parecer inesperada, enquanto um documento com nome genérico como arquivo1.pdf é difícil de identificar. Use linguagem clara, evite anexar várias versões e mantenha o conteúdo coerente com o pedido que originou o envio.

Teste a abertura em dispositivos diferentes e em conexões móveis. Uma imagem muito grande pode demorar ou consumir dados; prefira tamanho adequado à finalidade. Não comprima a ponto de tornar comprovantes ilegíveis. Para documentos, valide páginas, orientação, senha e se o arquivo não contém páginas de outra pessoa.

Controle arquivos temporários

Se seu sistema cria URLs assinadas, registre a expiração e evite que o worker tente usá-las depois do prazo. Se o envio falhar por URL expirada, gere um link novo somente depois de verificar se a solicitação continua válida. Não deixe arquivos temporários acessíveis sem autenticação por tempo indeterminado.

Armazene o status da transferência sem guardar uma cópia extra do conteúdo no log. Se uma mensagem não for aceita, preserve o arquivo em local seguro até decidir se deve tentar de novo; se não for mais necessário, remova conforme sua política. Evite sincronizar anexos para dispositivos pessoais de operadores sem razão aprovada.

Se o envio falhar, abra o endereço da mídia a partir de um ambiente externo, confira o código HTTP e examine a mensagem retornada pela API. Evite repetir rapidamente solicitações sem entender se uma tentativa anterior foi aceita, para não duplicar o conteúdo.

O resultado da API não substitui o acompanhamento do estado da instância. Para detalhes sobre armazenamento, uploads diários e renovação das cotas, consulte a página planos StackZap Cloud e o painel do seu ambiente.

Considere a experiência de quem recebe

Avise que o arquivo está chegando e descreva o que fazer com ele. Uma mídia sem legenda pode parecer inesperada, enquanto um documento com nome genérico como arquivo1.pdf é difícil de identificar. Use linguagem clara, evite anexar várias versões e mantenha o conteúdo coerente com o pedido que originou o envio.

Teste a abertura em dispositivos diferentes e em conexões móveis. Uma imagem muito grande pode demorar ou consumir dados; prefira tamanho adequado à finalidade. Não comprima a ponto de tornar comprovantes ilegíveis. Para documentos, valide páginas, orientação, senha e se o arquivo não contém páginas de outra pessoa.

Controle arquivos temporários

Se seu sistema cria URLs assinadas, registre a expiração e evite que o worker tente usá-las depois do prazo. Se o envio falhar por URL expirada, gere link novo somente depois de verificar se a solicitação continua válida. Não deixe arquivos temporários acessíveis sem autenticação por tempo indeterminado.

Armazene o status da transferência sem guardar cópia extra do conteúdo no log. Se uma mensagem não for aceita, preserve o arquivo em local seguro até decidir se deve tentar de novo; se não for necessário, remova conforme sua política. Evite sincronizar anexos para dispositivos pessoais sem razão aprovada.