Quickstart

You’ll need a connected Kirim organisation with at least one approved WhatsApp Business number. If you haven’t onboarded yet, sign up at app.kirim.dev and connect your number first — the dashboard walks you through the embedded Meta signup flow.

Goal

By the end of this page you’ll have:

1. Issued an API key.
2. Sent a text message to your own phone.
3. Polled the message status and seen delivered.

Total time: under five minutes if Meta is in a cooperative mood.

Steps

1. Issue an API key.

   In the Kirim dashboard, navigate to Developers → API Keys and click Create key. Give it a descriptive label (e.g. local-laptop or n8n-prod) and copy the plaintext value immediately — Kirim shows it exactly once.

   # Store the key in your shell — never commit it.
   export KIRIM_KEY=kdv_live_xxxxxxxxxxxxxxxxxxxxxxxx

   No second chances

   The plaintext is hashed at rest with argon2id. If you lose it before storing it somewhere safe, revoke the key and issue a new one.

2. Verify the key works.

   The /v1/me endpoint introspects your key and returns the organisation context.

   curl -sS https://api-kckit.kirim.chat/v1/me \
     -H "Authorization: Bearer $KIRIM_KEY"

   Expected response:

   {
     "data": {
       "organization": {
         "id": "org_…",
         "object": "organization",
         "name": "Your Org"
       },
       "api_key": {
         "id": "key_…",
         "object": "api_key",
         "label": "local-laptop",
         "last4": "abcd"
       },
       "rate_limits": {
         "tier": "default",
         "write_per_minute": 60,
         "read_per_minute": 600
       }
     },
     "request_id": "req_…"
   }

3. Send your first message.

   Replace +628123456789 with a phone number Meta has already received a message from in the past 24 hours — Meta only allows free-form text inside an open conversation window.

   curl

   curl -sS https://api-kckit.kirim.chat/v1/messages \
     -H "Authorization: Bearer $KIRIM_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "to": "+628123456789",
       "type": "text",
       "text": { "body": "Halo dari Kirim API" }
     }'

   Node.js

   const res = await fetch('https://api-kckit.kirim.chat/v1/messages', {
     method: 'POST',
     headers: {
       'Authorization': `Bearer ${process.env.KIRIM_KEY}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       to: '+628123456789',
       type: 'text',
       text: { body: 'Halo dari Kirim API' },
     }),
   })
   const json = await res.json()
   console.log(json.data.id) // -> msg_...

   Python

   import os
   import httpx
   
   r = httpx.post(
       "https://api-kckit.kirim.chat/v1/messages",
       headers={"Authorization": f"Bearer {os.environ['KIRIM_KEY']}"},
       json={
           "to": "+628123456789",
           "type": "text",
           "text": {"body": "Halo dari Kirim API"},
       },
   )
   print(r.json()["data"]["id"])  # -> msg_...

   Expected response:

   {
     "data": {
       "id": "msg_01HXYZABCDEFGHJKMNPQRSTVWX",
       "object": "message",
       "to": "+628123456789",
       "type": "text",
       "status": "pending",
       "created_at": "2026-05-24T08:00:00.000Z"
     },
     "request_id": "req_…"
   }

   The recipient should receive the message within a few seconds.

4. Poll the status.

   The send is asynchronous — status flips from pending → sent → delivered → read as Meta returns callbacks.

   curl -sS https://api-kckit.kirim.chat/v1/messages/msg_01HXYZABCDEFGHJKMNPQRSTVWX \
     -H "Authorization: Bearer $KIRIM_KEY"

   {
     "data": {
       "id": "msg_01HXYZABCDEFGHJKMNPQRSTVWX",
       "object": "message",
       "status": "delivered",
       "to": "+628111111111",
       "type": "text",
       "created_at": "…"
     },
     "request_id": "…"
   }

   Polling is fine for a quickstart but inefficient at scale. Set up a webhook (next section) to receive message.status callbacks instead.

What’s next

• Subscribe to webhooks so you stop polling and start receiving events as they happen.
• Authentication deep dive — key rotation, expiration, security guidance.
• Handle failed sends — the structured error envelope and stable error codes you can branch on.
• Browse the API reference — every endpoint, generated live from the OpenAPI spec.