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

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

curl --request POST \
  --url https://{space}.{region}.api.niadra.com/v1/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
      }
    ]
  })
};

fetch('https://{space}.{region}.api.niadra.com/v1/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{space}.{region}.api.niadra.com/v1/batch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://{space}.{region}.api.niadra.com/v1/batch"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"type\": \"event\",\n      \"kind\": \"message\",\n      \"idempotency_key\": \"wamid.HBgLMTQxNTU1NTAxMjMVAgASGBQzQUQ\",\n      \"channel\": \"whatsapp\",\n      \"conversation_id\": \"wa-8812\",\n      \"handles\": [\n        {\n          \"type\": \"phone_e164\",\n          \"value\": \"+14155550123\"\n        }\n      ],\n      \"speaker\": {\n        \"role\": \"customer\"\n      },\n      \"direction\": \"inbound\",\n      \"content\": {\n        \"type\": \"text\",\n        \"text\": \"The technician never showed up. I am calling you.\"\n      },\n      \"occurred_at\": \"2026-09-22T17:02:11Z\"\n    },\n    {\n      \"type\": \"event\",\n      \"kind\": \"action\",\n      \"idempotency_key\": \"0192f7a1-6c1e-7c3a-9b1e-5d2f8a4c0e11\",\n      \"channel\": \"erp\",\n      \"task_id\": \"billing-7741\",\n      \"handles\": [\n        {\n          \"type\": \"system_id\",\n          \"value\": \"48213\",\n          \"scope\": \"crm\"\n        }\n      ],\n      \"object_refs\": [\n        {\n          \"type\": \"invoice\",\n          \"namespace\": \"erp\",\n          \"id\": \"0823\"\n        }\n      ],\n      \"speaker\": {\n        \"role\": \"ai_agent\",\n        \"id\": \"billing-agent\"\n      },\n      \"action\": {\n        \"operation\": \"credit\",\n        \"result\": \"$40 credit on the August bill\",\n        \"closes\": {\n          \"object\": {\n            \"type\": \"invoice\",\n            \"namespace\": \"erp\",\n            \"id\": \"0823\"\n          },\n          \"operation\": \"dispute\"\n        }\n      },\n      \"occurred_at\": \"2026-09-22T17:06:21Z\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{space}.{region}.api.niadra.com/v1/batch")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"type\": \"event\",\n      \"kind\": \"message\",\n      \"idempotency_key\": \"wamid.HBgLMTQxNTU1NTAxMjMVAgASGBQzQUQ\",\n      \"channel\": \"whatsapp\",\n      \"conversation_id\": \"wa-8812\",\n      \"handles\": [\n        {\n          \"type\": \"phone_e164\",\n          \"value\": \"+14155550123\"\n        }\n      ],\n      \"speaker\": {\n        \"role\": \"customer\"\n      },\n      \"direction\": \"inbound\",\n      \"content\": {\n        \"type\": \"text\",\n        \"text\": \"The technician never showed up. I am calling you.\"\n      },\n      \"occurred_at\": \"2026-09-22T17:02:11Z\"\n    },\n    {\n      \"type\": \"event\",\n      \"kind\": \"action\",\n      \"idempotency_key\": \"0192f7a1-6c1e-7c3a-9b1e-5d2f8a4c0e11\",\n      \"channel\": \"erp\",\n      \"task_id\": \"billing-7741\",\n      \"handles\": [\n        {\n          \"type\": \"system_id\",\n          \"value\": \"48213\",\n          \"scope\": \"crm\"\n        }\n      ],\n      \"object_refs\": [\n        {\n          \"type\": \"invoice\",\n          \"namespace\": \"erp\",\n          \"id\": \"0823\"\n        }\n      ],\n      \"speaker\": {\n        \"role\": \"ai_agent\",\n        \"id\": \"billing-agent\"\n      },\n      \"action\": {\n        \"operation\": \"credit\",\n        \"result\": \"$40 credit on the August bill\",\n        \"closes\": {\n          \"object\": {\n            \"type\": \"invoice\",\n            \"namespace\": \"erp\",\n            \"id\": \"0823\"\n          },\n          \"operation\": \"dispute\"\n        }\n      },\n      \"occurred_at\": \"2026-09-22T17:06:21Z\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{space}.{region}.api.niadra.com/v1/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"type\": \"event\",\n      \"kind\": \"message\",\n      \"idempotency_key\": \"wamid.HBgLMTQxNTU1NTAxMjMVAgASGBQzQUQ\",\n      \"channel\": \"whatsapp\",\n      \"conversation_id\": \"wa-8812\",\n      \"handles\": [\n        {\n          \"type\": \"phone_e164\",\n          \"value\": \"+14155550123\"\n        }\n      ],\n      \"speaker\": {\n        \"role\": \"customer\"\n      },\n      \"direction\": \"inbound\",\n      \"content\": {\n        \"type\": \"text\",\n        \"text\": \"The technician never showed up. I am calling you.\"\n      },\n      \"occurred_at\": \"2026-09-22T17:02:11Z\"\n    },\n    {\n      \"type\": \"event\",\n      \"kind\": \"action\",\n      \"idempotency_key\": \"0192f7a1-6c1e-7c3a-9b1e-5d2f8a4c0e11\",\n      \"channel\": \"erp\",\n      \"task_id\": \"billing-7741\",\n      \"handles\": [\n        {\n          \"type\": \"system_id\",\n          \"value\": \"48213\",\n          \"scope\": \"crm\"\n        }\n      ],\n      \"object_refs\": [\n        {\n          \"type\": \"invoice\",\n          \"namespace\": \"erp\",\n          \"id\": \"0823\"\n        }\n      ],\n      \"speaker\": {\n        \"role\": \"ai_agent\",\n        \"id\": \"billing-agent\"\n      },\n      \"action\": {\n        \"operation\": \"credit\",\n        \"result\": \"$40 credit on the August bill\",\n        \"closes\": {\n          \"object\": {\n            \"type\": \"invoice\",\n            \"namespace\": \"erp\",\n            \"id\": \"0823\"\n          },\n          \"operation\": \"dispute\"\n        }\n      },\n      \"occurred_at\": \"2026-09-22T17:06:21Z\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "accepted": 2,
  "duplicates": 0,
  "errors": []
}

{
  "accepted": 1,
  "duplicates": 0,
  "errors": [
    {
      "index": 1,
      "code": "scope_missing",
      "detail": "the key lacks the act scope"
    }
  ]
}