> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Enviar um lote > Mensagens, eventos de sistema, ações, identificação e verificação num lote só, com erro por item. ## OpenAPI ````yaml openapi/pt/cell.json POST /v1/batch openapi: 3.1.0 info: title: API de dados da Niadra version: '1' description: >- Escrita, contexto, histórico, objetos, identidade, privacidade e governança de um espaço. Cada espaço tem um endereço estável, com o espaço e a região no nome. servers: - url: https://{space}.{region}.api.niadra.com variables: space: default: acme-prod description: O espaço, que vem na chave de fonte. region: default: us-east-1 description: A região do espaço, que também vem na chave. security: [] paths: /v1/batch: post: tags: - ingest summary: Enviar um lote description: >- Até 500 itens de tipos misturados: mensagens, eventos de sistema, ações, `identify`, `verify`, `handoff` e o fim de uma conversa ou tarefa. O evento bruto é gravado antes da resposta e deduplicado pelo `idempotency_key`, então repetir é sempre seguro. Os itens são validados um a um: quando todos entram, a resposta é 200; quando algum é recusado, é 207, com uma entrada por item recusado em `errors`, nunca um 422 para o lote inteiro. Os escopos são conferidos por item: `track` para eventos, `act` para ações, `identify` para identificação. **Autenticação.** Chave de fonte: `Authorization: Bearer nia_sk_...`. Os escopos são conferidos item a item: `track` para eventos, `act` para ações, `identify` para identificação. operationId: batch_v1_batch_post requestBody: content: application/json: schema: $id: urn:niadra:v1:batch-request additionalProperties: false properties: items: items: discriminator: mapping: conversation.ended: $ref: '#/components/schemas/ConversationEndedItem' event: $ref: '#/components/schemas/EventItem' handoff: $ref: '#/components/schemas/HandoffItem' heartbeat: $ref: '#/components/schemas/HeartbeatItem' identify: $ref: '#/components/schemas/IdentifyItem' task.ended: $ref: '#/components/schemas/TaskEndedItem' verify: $ref: '#/components/schemas/VerifyItem' propertyName: type oneOf: - $ref: '#/components/schemas/EventItem' - $ref: '#/components/schemas/IdentifyItem' - $ref: '#/components/schemas/VerifyItem' - $ref: '#/components/schemas/ConversationEndedItem' - $ref: '#/components/schemas/TaskEndedItem' - $ref: '#/components/schemas/HandoffItem' - $ref: '#/components/schemas/HeartbeatItem' maxItems: 500 minItems: 1 title: Items type: array required: - items title: BatchRequest type: object example: items: - type: event kind: message idempotency_key: wamid.HBgLMTQxNTU1NTAxMjMVAgASGBQzQUQ channel: whatsapp conversation_id: wa-8812 handles: - type: phone_e164 value: '+14155550123' speaker: role: customer direction: inbound content: type: text text: The technician never showed up. I am calling you. occurred_at: '2026-09-22T17:02:11Z' - type: event kind: action idempotency_key: 0192f7a1-6c1e-7c3a-9b1e-5d2f8a4c0e11 channel: erp task_id: billing-7741 handles: - type: system_id value: '48213' scope: crm object_refs: - type: invoice namespace: erp id: '0823' speaker: role: ai_agent id: billing-agent action: operation: credit result: $40 credit on the August bill closes: object: type: invoice namespace: erp id: '0823' operation: dispute occurred_at: '2026-09-22T17:06:21Z' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/BatchResponse' example: accepted: 2 duplicates: 0 errors: [] description: Todos os itens entraram ou foram reconhecidos como duplicados. '207': content: application/json: schema: $ref: '#/components/schemas/BatchResponse' example: accepted: 1 duplicates: 0 errors: - index: 1 code: scope_missing detail: the key lacks the act scope description: Aceito, com o resultado de cada item. security: - sourceKey: [] x-codeSamples: - lang: python label: Python source: >- from niadra import Niadra, phone, system_id niadra = Niadra() # reads NIADRA_API_KEY # Queued and sent in the background, in batches niadra.track({ "channel": "whatsapp", "conversation_id": "wa-8812", "idempotency_key": message["id"], # the provider message id "handles": [phone("+14155550123")], "speaker": {"role": "customer"}, "content": {"text": "The technician never showed up. I am calling you."}, }) niadra.action( "credit", subject=system_id("crm", "48213"), object="invoice:erp:0823", result="$40 credit on the August bill", closes={"object": {"type": "invoice", "namespace": "erp", "id": "0823"}, "operation": "dispute"}, channel="erp", task_id="billing-7741", ) niadra.flush() # waits for the queue, for example before a worker exits - lang: typescript label: TypeScript source: >- import { Niadra, handles } from "@niadra/sdk"; const niadra = new Niadra(); // reads NIADRA_API_KEY // Queued and sent in the background, in batches niadra.track({ channel: "whatsapp", conversation_id: "wa-8812", idempotency_key: message.id, // the provider message id handles: [handles.phone("+14155550123")], speaker: "customer", text: "The technician never showed up. I am calling you.", }); niadra.action({ channel: "erp", task_id: "billing-7741", handles: [handles.systemId("48213", "crm")], object_refs: ["invoice:erp:0823"], operation: "credit", result: "$40 credit on the August bill", closes: { object: { type: "invoice", namespace: "erp", id: "0823" }, operation: "dispute" }, }); await niadra.flush(); // waits for the queue, for example before a worker exits components: schemas: ConversationEndedItem: additionalProperties: false properties: conversation_id: maxLength: 512 minLength: 1 title: Conversation Id type: string idempotency_key: maxLength: 512 minLength: 1 title: Idempotency Key type: string occurred_at: format: date-time title: Occurred At type: string type: const: conversation.ended default: conversation.ended title: Type type: string required: - idempotency_key - conversation_id - occurred_at title: ConversationEndedItem type: object description: >- Fecha a sessão na hora, sem esperar a inatividade. Envie no fim de toda ligação. EventItem: additionalProperties: false description: >- Uma mensagem, um evento de sistema ou uma ação de agente. A mensagem precisa de texto, transcrição ou referência de mídia; o evento de sistema precisa de `canonical_type`; a ação precisa do bloco `action`. Todo evento precisa de ao menos um handle, sujeito ou objeto. properties: action: anyOf: - $ref: '#/components/schemas/ActionInfo' - type: 'null' canonical_type: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' description: Só em eventos de sistema, como `invoice.credited`. title: Canonical Type channel: maxLength: 256 minLength: 1 title: Channel type: string description: >- Onde aconteceu: `whatsapp`, `voice`, `app`, `email`, `erp`, `crm`, `ticket`. content: anyOf: - $ref: '#/components/schemas/Content' - type: 'null' context_stamp: anyOf: - $ref: '#/components/schemas/ContextStamp' - type: 'null' conversation_aliases: items: maxLength: 512 minLength: 1 type: string maxItems: 8 title: Conversation Aliases type: array description: >- Outros ids da mesma conversa, como o id da plataforma e o id do tronco de uma ligação. conversation_id: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Conversation Id description: >- O seu id da conversa. Uma conversa de WhatsApp pode durar meses; a Niadra a divide em sessões. corrects_event_id: anyOf: - type: string - type: 'null' title: Corrects Event Id direction: anyOf: - enum: - inbound - outbound type: string - type: 'null' title: Direction fields: additionalProperties: true description: Os campos estruturados de um evento de sistema. title: Fields type: object handles: items: $ref: '#/components/schemas/Handle' maxItems: 16 title: Handles type: array description: Os handles da pessoa de quem o evento fala. idempotency_key: description: >- O id da mensagem no provedor, ou um UUIDv7 gerado pelo SDK. Uma chave repetida conta como duplicata e nunca é gravada duas vezes. maxLength: 512 minLength: 1 title: Idempotency Key type: string kind: $ref: '#/components/schemas/EventKind' default: message description: O padrão é `message`. object_refs: items: $ref: '#/components/schemas/ObjectRef' maxItems: 16 title: Object Refs type: array description: Pedidos, tickets e faturas de que o evento fala. occurred_at: format: date-time title: Occurred At type: string description: >- Quando aconteceu na origem. Os eventos são ordenados por este campo, nunca pela chegada. speaker: $ref: '#/components/schemas/SpeakerRef' subjects: items: $ref: '#/components/schemas/Subject' maxItems: 8 title: Subjects type: array description: >- Use no lugar de `handles` quando o evento fala de mais de um sujeito. task_id: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Task Id description: O seu id da tarefa de um agente interno. type: const: event default: event title: Type type: string verification_hint: anyOf: - $ref: '#/components/schemas/Verification' - type: 'null' visibility: $ref: '#/components/schemas/Visibility' default: public description: O padrão é `public`. voice: anyOf: - $ref: '#/components/schemas/VoiceInfo' - type: 'null' required: - idempotency_key - channel - speaker - occurred_at title: EventItem type: object HandoffItem: additionalProperties: false description: >- Uma transferência para um humano ou para outro agente. A medição do aproveitamento do contexto lê este evento. properties: conversation_id: maxLength: 512 minLength: 1 title: Conversation Id type: string idempotency_key: maxLength: 512 minLength: 1 title: Idempotency Key type: string mode: default: warm enum: - warm - cold title: Mode type: string description: '`warm` quando quem recebe ganha um briefing. O padrão é `warm`.' occurred_at: format: date-time title: Occurred At type: string reason: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Reason target: enum: - human - agent title: Target type: string target_source: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Target Source description: A fonte que assume, quando ela está integrada à Niadra. type: const: handoff default: handoff title: Type type: string required: - idempotency_key - conversation_id - target - occurred_at title: HandoffItem type: object HeartbeatItem: additionalProperties: false description: >- Contadores periódicos do SDK, usados para calcular a cobertura por fonte. properties: sent: minimum: 0 title: Sent type: integer description: Os eventos que o SDK enviou na janela. type: const: heartbeat default: heartbeat title: Type type: string window_start: format: date-time title: Window Start type: string required: - window_start - sent title: HeartbeatItem type: object IdentifyItem: additionalProperties: false description: Afirma que vários handles pertencem ao mesmo sujeito. properties: conversation_id: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Conversation Id handles: items: $ref: '#/components/schemas/Handle' maxItems: 16 minItems: 2 title: Handles type: array description: Os handles que pertencem ao mesmo sujeito. idempotency_key: maxLength: 512 minLength: 1 title: Idempotency Key type: string method: $ref: '#/components/schemas/AssertionMethod' default: explicit_identify description: O padrão é `explicit_identify`. occurred_at: format: date-time title: Occurred At type: string subject_kind: $ref: '#/components/schemas/SubjectKind' default: person description: >- O padrão é `person`. Handles de tipos de sujeito diferentes nunca são ligados por uma asserção. type: const: identify default: identify title: Type type: string required: - idempotency_key - handles - occurred_at title: IdentifyItem type: object TaskEndedItem: additionalProperties: false properties: idempotency_key: maxLength: 512 minLength: 1 title: Idempotency Key type: string occurred_at: format: date-time title: Occurred At type: string task_id: maxLength: 512 minLength: 1 title: Task Id type: string type: const: task.ended default: task.ended title: Type type: string required: - idempotency_key - task_id - occurred_at title: TaskEndedItem type: object description: Fecha a sessão da tarefa de um agente interno. VerifyItem: additionalProperties: false description: >- Eleva o nível de verificação de uma conversa ou tarefa. Nunca é inferido. Um nível acima do teto da fonte volta como erro de item `verification_not_allowed`. properties: conversation_id: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Conversation Id handle: $ref: '#/components/schemas/Handle' description: O handle cuja posse foi provada. idempotency_key: maxLength: 512 minLength: 1 title: Idempotency Key type: string level: $ref: '#/components/schemas/Verification' method: enum: - otp_whatsapp - otp_sms - login - kba - network_attestation - human_agent title: Method type: string occurred_at: format: date-time title: Occurred At type: string task_id: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Task Id type: const: verify default: verify title: Type type: string valid_until: anyOf: - format: date-time type: string - type: 'null' title: Valid Until required: - idempotency_key - method - level - handle - occurred_at title: VerifyItem type: object BatchResponse: additionalProperties: false properties: accepted: title: Accepted type: integer duplicates: title: Duplicates type: integer description: Itens cuja chave de idempotência já estava gravada. errors: items: $ref: '#/components/schemas/ItemError' title: Errors type: array required: - accepted - duplicates - errors title: BatchResponse type: object ActionInfo: additionalProperties: false properties: closes: anyOf: - $ref: '#/components/schemas/Closes' - type: 'null' corrects_action_id: anyOf: - type: string - type: 'null' title: Corrects Action Id description: >- Uma ação é imutável; a correção é uma ação nova que aponta para a anterior. operation: description: Operação canônica, como `credit` ou `reschedule`. maxLength: 256 minLength: 1 title: Operation type: string purpose: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Purpose result: anyOf: - maxLength: 2000 type: string - type: 'null' title: Result required: - operation title: ActionInfo type: object description: >- Obrigatório quando `kind` é `action`, e só vale nesse caso. Exige o escopo `act`. Content: additionalProperties: false properties: media_ref: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' description: A referência devolvida por `POST /v1/media/uploads`. title: Media Ref media_sha256: anyOf: - pattern: ^[0-9a-f]{64}$ type: string - type: 'null' title: Media Sha256 description: SHA-256 da mídia, em hexadecimal. stt_confidence: anyOf: - maximum: 1 minimum: 0 type: number - type: 'null' title: Stt Confidence description: Confiança da transcrição de voz, de 0 a 1. text: anyOf: - maxLength: 200000 type: string - type: 'null' title: Text transcript: anyOf: - maxLength: 200000 type: string - type: 'null' title: Transcript type: default: text enum: - text - audio - image - file title: Type type: string title: Content type: object description: >- O que foi dito ou enviado. Mídia nunca viaja dentro do evento: faça o upload antes e passe a referência. ContextStamp: additionalProperties: false description: >- Qual contexto o prompt do agente levava e quando ele entrou: o SDK carimba isso no turno do agente, e a medição distingue um contexto atrasado de um contexto não usado. properties: etag: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Etag injected_at: format: date-time title: Injected At type: string required: - injected_at title: ContextStamp type: object Handle: additionalProperties: false description: >- Um identificador de um sujeito num canal ou sistema: um telefone, um e-mail, um id do CRM. properties: scope: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' description: >- Espaço de nomes dos identificadores com escopo: a conta do WhatsApp Business para `wa_bsuid`, o sistema para `system_id`, o país para `gov_id_hmac`. title: Scope subject_kind: anyOf: - $ref: '#/components/schemas/SubjectKind' - type: 'null' description: >- O padrão é `person`, exceto nos tipos de handle que só identificam organizações. type: $ref: '#/components/schemas/HandleType' value: maxLength: 320 minLength: 1 title: Value type: string description: >- O identificador. Normalizado no servidor: E.164 para telefone, minúsculas para e-mail. required: - type - value title: Handle type: object EventKind: enum: - message - system_event - action title: EventKind type: string description: >- O que um evento registra: algo que foi dito, uma mudança num sistema de registro ou o que um agente fez num sistema. ObjectRef: additionalProperties: false description: Um objeto de negócio num sistema de registro. properties: id: maxLength: 512 minLength: 1 title: Id type: string description: O id nesse sistema. namespace: maxLength: 256 minLength: 1 title: Namespace type: string description: O sistema onde ele vive, como `erp`. type: maxLength: 256 minLength: 1 title: Type type: string description: Tipo do objeto, como `invoice`, `order` ou `ticket`. required: - type - namespace - id title: ObjectRef type: object SpeakerRef: additionalProperties: false properties: id: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' description: O id do agente ou do atendente dentro da fonte. title: Id role: $ref: '#/components/schemas/Speaker' required: - role title: SpeakerRef type: object Subject: additionalProperties: false properties: handles: items: $ref: '#/components/schemas/Handle' maxItems: 16 minItems: 1 title: Handles type: array kind: $ref: '#/components/schemas/SubjectKind' role: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Role description: O papel da pessoa no evento, como `driver` ou `buyer`. required: - kind - handles title: Subject type: object description: >- Um dos sujeitos de um evento, quando o evento fala de mais de um (o motorista e a transportadora). Verification: description: >- Nível de verificação da sessão. V0 autodeclarado, V1 plausível pelo canal, V2 atestado pelo canal, V3 desafiado (OTP ou login), V4 conferido com um sistema de registro ou por um atendente. `no_customer` vale para tarefas sem cliente presente e só é aceito de fontes de agente interno. enum: - V0 - V1 - V2 - V3 - V4 - no_customer title: Verification type: string Visibility: enum: - public - internal title: Visibility type: string description: >- `internal` marca notas que o cliente nunca viu, como a anotação de um atendente. VoiceInfo: additionalProperties: false properties: ani: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Ani description: Número de quem ligou. answered_at: anyOf: - format: date-time type: string - type: 'null' title: Answered At dnis: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Dnis description: Número discado. end_reason: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: End Reason ended_at: anyOf: - format: date-time type: string - type: 'null' title: Ended At network_attestation: anyOf: - enum: - A - B - C type: string - type: 'null' title: Network Attestation description: >- Nível de atestado de rede da ligação (STIR/SHAKEN e equivalentes). A vira V2; B e C viram V1. recording_ref: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Recording Ref trunk: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Trunk turn_offset_ms: anyOf: - minimum: 0 type: integer - type: 'null' title: Turn Offset Ms description: Distância deste turno em relação ao início da ligação. title: VoiceInfo type: object description: Metadados da ligação, nos eventos de voz. AssertionMethod: enum: - explicit_identify - otp - login - system_import - same_event - co_occurrence - channel_rotation - accepted_suggestion - external_resolver - declared title: AssertionMethod type: string description: Como a ligação entre dois handles foi estabelecida. SubjectKind: enum: - person - account - partner title: SubjectKind type: string description: >- Uma pessoa, uma organização cliente (`account`) ou uma organização que participa sem ser cliente (`partner`). ItemError: additionalProperties: false properties: code: title: Code type: string detail: anyOf: - type: string - type: 'null' title: Detail index: title: Index type: integer description: A posição do item em `items`. required: - index - code title: ItemError type: object Closes: additionalProperties: false description: >- A pendência que uma ação cumpre: pelo `item_id`, ou pelo `object` junto da `operation` canônica. Exatamente uma das duas formas. properties: item_id: anyOf: - type: string - type: 'null' title: Item Id description: O id da pendência. object: anyOf: - $ref: '#/components/schemas/ObjectRef' - type: 'null' operation: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Operation description: Operação canônica, junto de `object`. title: Closes type: object HandleType: enum: - phone_e164 - wa_id - wa_jid - wa_lid - wa_bsuid - email - gov_id_hmac - app_user_id - system_id - org_registry_hmac - email_domain - anon_id title: HandleType type: string description: >- O tipo de identificador. O valor é classificado pelo formato, nunca pelo campo de onde veio. Speaker: enum: - customer - ai_agent - human_agent - system title: Speaker type: string description: Quem produziu o evento. securitySchemes: sourceKey: type: http scheme: bearer description: nia_sk_... ````