Enviar PDF e outros anexos

Para enviar um PDF ou outro anexo compatível, solicite um upload ao Bridge, envie os bytes do arquivo à URL retornada e crie uma mensagem com o mediaId recebido. O exemplo completo no servidor abaixo envia um PDF.

Antes de começar

Tenha uma conversa existente no workspace desejado. Veja primeira conversa.
Escolha um PDF que você tem autorização para compartilhar e confirme se ele atende aos limites da API de arquivos.
Mantenha a chave de API do Bridge no servidor. Não a acrescente à requisição de upload pré-assinada.
Escolha explicitamente o sinalizador enableExternalBroadcast da mensagem.

Valide o arquivo antes de solicitar um upload

Verifique o arquivo real no seu servidor: a extensão, o tipo MIME e o tamanho em bytes devem cumprir as regras publicadas da API de arquivos. A requisição de URL pré-assinada contém metadados e um checksum, não os bytes do arquivo nem um campo de tamanho. Uma resposta 201 prepara um upload; não comprova que os bytes reais foram inspecionados, que o tamanho enviado cumpre os limites publicados ou que um provedor de mensagens aceitará o arquivo. Se você omitir contentType, ainda assim copie presignUrl.headers para a requisição PUT: a Bridge pode deduzir Content-Type pelo nome do arquivo. Se o informar, use o tipo MIME do arquivo real e mantenha-o coerente com fileType e a extensão. Renomear um arquivo não converte seu conteúdo. Após um PUT bem-sucedido, o processamento do upload ainda pode estar pendente. Se uma requisição de Message retornar um erro de upload de arquivos, preserve o erro completo e confira a etapa que falhou antes de decidir se outra gravação é segura.

Sequência de upload

Etapa	O que acontece	O que ela não confirma
`POST .../files`	O Bridge retorna `mediaId` e os dados de `presignUrl`.	Os bytes ainda não foram enviados.
`PUT` pré-assinado	Seu servidor envia exatamente os bytes do arquivo usando a URL de upload e os cabeçalhos retornados.	Essa etapa não cria uma mensagem.
`POST .../messages`	Você anexa o `mediaId` do arquivo enviado por meio de `mediaIds`.	A resposta da API, sozinha, não comprova a entrega pelo provedor.

O checksum é o digest SHA-256 de todos os bytes do arquivo, codificado em Base64. Não é um digest hexadecimal nem o hash do nome do arquivo.

Exemplo completo no servidor

Use Node.js com fetch nativo. Salve como send-attachment.mjs. Defina BRIDGE_API_KEY, BRIDGE_WORKSPACE_ID, BRIDGE_CONVERSATION_ID, ATTACHMENT_PATH e ENABLE_EXTERNAL_BROADCAST (true ou false).

import { readFile } from "node:fs/promises";
import { basename } from "node:path";
import { createHash } from "node:crypto";

const BASE = "https://api-connect-us.bridge.new";
function required(name) {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} before running this example.`);
  return value;
}
const apiKey = required("BRIDGE_API_KEY");
const workspaceId = required("BRIDGE_WORKSPACE_ID");
const conversationId = required("BRIDGE_CONVERSATION_ID");
const filePath = required("ATTACHMENT_PATH");
const broadcast = required("ENABLE_EXTERNAL_BROADCAST");
if (!["true", "false"].includes(broadcast)) {
  throw new Error("ENABLE_EXTERNAL_BROADCAST must be true or false.");
}
if (!filePath.toLowerCase().endsWith(".pdf")) {
  throw new Error("This example is configured for a PDF document.");
}
const workspacePath = `/bridge/api/v1/workspaces/${encodeURIComponent(workspaceId)}`;
const bytes = await readFile(filePath);
const checksumBase64 = createHash("sha256").update(bytes).digest("base64");

async function bridgePost(path, body) {
  const response = await fetch(`${BASE}${workspacePath}${path}`, {
    method: "POST",
    headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  const result = await response.json().catch(() => null);
  if (response.status !== 201) {
    const code = result?.code ? ` (${result.code})` : "";
    throw new Error(`Bridge ${path}: HTTP ${response.status}${code}`);
  }
  return result;
}

const uploads = await bridgePost("/files", [{
  name: basename(filePath),
  fileType: "DOCUMENT",
  contentType: "application/pdf",
  checksumBase64,
}]);
const upload = uploads?.[0];
if (!upload?.mediaId || !upload.presignUrl?.url) {
  throw new Error("The upload response is missing its mediaId or URL.");
}
const method = upload.presignUrl.method ?? "PUT";
if (method !== "PUT") throw new Error("Expected a presigned PUT upload.");
const uploadHeaders = new Headers(upload.presignUrl.headers ?? {});
const returnedChecksum = uploadHeaders.get("x-amz-checksum-sha256");
if (returnedChecksum !== null && returnedChecksum !== checksumBase64) {
  throw new Error("The returned checksum differs from the file checksum.");
}
if (returnedChecksum === null) {
  uploadHeaders.set("x-amz-checksum-sha256", checksumBase64);
}

const uploaded = await fetch(upload.presignUrl.url, {
  method,
  headers: uploadHeaders,
  body: bytes,
});
if (!uploaded.ok) {
  throw new Error(`File upload failed: HTTP ${uploaded.status}; no Message was created.`);
}

const message = await bridgePost("/messages", {
  conversationId,
  messageBody: "Here is the document you requested.",
  enableExternalBroadcast: broadcast === "true",
  mediaIds: [upload.mediaId],
});
if (!message?.messageId) throw new Error("The Message response has no messageId.");
console.log({ mediaId: upload.mediaId, messageId: message.messageId });

node send-attachment.mjs

Preserve a requisição de upload

Use presignUrl.url sem reconstruir o host, o caminho ou a query string. Use o método e os cabeçalhos obrigatórios retornados. O contrato define PUT como método padrão quando o campo é omitido, e a API de arquivos exige x-amz-checksum-sha256 com o mesmo checksum enviado ao Bridge. O upload envia os mesmos bytes usados para calcular o checksum. Não converta o PDF em texto, não o encapsule em JSON e não envie uma cópia diferente após calcular o hash. Para vários arquivos, preserve a associação entre cada mediaId retornado, os dados pré-assinados e o arquivo correspondente. Conclua todos os uploads necessários antes de anexar os IDs a uma mensagem. Algumas mídias precisam de mais preparação após o upload, como copiar o arquivo, gerar uma prévia, converter ou enviar o arquivo ao provedor de mensagens. Essas etapas podem falhar de forma independente. Um PUT bem-sucedido ou uma resposta 201 ao criar a mensagem não comprovam que o processamento ou a entrega pelo provedor foram concluídos. Mantenha o arquivo original e os identificadores recebidos para correlacionar o resultado antes de repetir uma requisição de mensagem.

Trate uma falha em cada etapa

O Bridge rejeita a solicitação de arquivo: confira extensão, fileType, tipo de conteúdo, tamanho e checksum na referência.
O upload falha: pare antes de criar a mensagem. Verifique URL, método, cabeçalhos, checksum e bytes exatos. Não presuma um prazo de validade ou uma política de novas tentativas que a resposta não informe.
A requisição de mensagem falha ou expira: um arquivo enviado não comprova a existência de uma mensagem. Verifique o resultado antes de repetir a requisição de mensagem.

STICKER e WEBSITE aparecem no enum FileType, mas a tabela pública de upload não especifica suas regras de extensão, MIME e tamanho. Confirme essas regras antes de escolher qualquer um deles para uma integração. Veja a API de arquivos, a API de mensagens e o guia de respostas e erros.

Comece aqui

Crie sua integração

Referência