Build on BotCrafter

API reference

Sending & building

Four things an integration typically does: send a message, send a template, and build or publish a bot flow.

POST/api/v1/notify

Sends a free-form text message through a connected number.

Body

# cURL
curl -X POST https://api.botcrafter.in/api/v1/notify \
  -H "Authorization: Bearer $BOTCRAFTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "8e2c...f01a",
    "to": "+15551234567",
    "message": "Hi Jane — your 3pm appointment is confirmed."
  }'

POST/api/v1/integrations/templates/:id/send

Sends an approved template — the way to reach someone outside the 24h window, or to guarantee delivery regardless of when they last wrote in.

Body

# cURL — parameters fill the template's {{1}}, {{2}}... in order
curl -X POST https://api.botcrafter.in/api/v1/integrations/templates/tmpl_9f21/send \
  -H "Authorization: Bearer $BOTCRAFTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "8e2c...f01a",
    "to": "+15551234567",
    "parameters": ["Jane", "Friday 3:00 PM"]
  }'

GET/api/v1/integrations/templates

Lists every template on the account, so you can find an approved one's id before sending it.

{
  "success": true,
  "data": [
    {
      "id": "tmpl_9f21",
      "name": "appointment_reminder",
      "language": "en_US",
      "category": "UTILITY",
      "status": "approved"
    }
  ]
}

status is one of draft pending approved rejected — only approved can be sent.

Build & publish a flow

A bot flow is built the same way whether it comes from the visual builder or from your own app: create it, shape its graph, point it at a number, publish it. These five calls are that lifecycle.

Creates an empty flow.

curl -X POST $BASE_URL/api/v1/integrations/flows \
  -H "Authorization: Bearer $BOTCRAFTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Appointment reminder" }'
# → { "success": true, "data": { "id": "flow_c81a" } }

Lists every flow on the account — id, name, status, and which number it's assigned to.

Fetches one flow, including its full graph — the node/edge shape the builder produces.

Replaces the flow's name and graph.

curl -X PUT $BASE_URL/api/v1/integrations/flows/flow_c81a \
  -H "Authorization: Bearer $BOTCRAFTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminder",
    "graph": {
      "nodes": [
        { "id": "n1", "type": "trigger", "position": {"x":0,"y":0}, "data": {} },
        { "id": "n2", "type": "message", "position": {"x":0,"y":160},
          "data": { "text": "Hi {{contact.name}}, this is a reminder about your visit." } }
      ],
      "edges": [ { "id": "e1", "source": "n1", "target": "n2" } ]
    }
  }'

Assigns which connected number the flow runs on.

curl -X PUT $BASE_URL/api/v1/integrations/flows/flow_c81a/connection \
  -H "Authorization: Bearer $BOTCRAFTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connection_id": "8e2c...f01a" }'

Publishes a draft flow — it starts running for real customers on its assigned number.

Webhooks

Receiving messages

There's no "check for new messages" endpoint to poll — instead, your app gets every inbound WhatsApp event pushed to it the moment it happens.

1. Pick a URL on your own appSomething like https://your-app.example.com/webhooks/botcrafter that accepts a POST with a JSON body. It needs to be publicly reachable — BotCrafter has to be able to call it.
2. Register it in the dashboardUnder Settings → Connections → Your own backend, set that URL and choose a secret (min. 8 characters — you invent this, it isn't issued to you). Use Test to confirm delivery works before relying on it.
3. Verify and handle deliveriesEvery delivery carries an HMAC signature made with that same secret — see Verifying signatures below.

Delivery

{
  "event": "message.received",
  "timestamp": "2026-08-22T10:04:11Z",
  "data": {
    "connection_id": "8e2c...f01a",
    "from": "+15551234567",
    "contact_name": "Jane Doe",
    "type": "text",
    "body": "Can I reschedule to Monday?",
    "media_url": ""
  }
}

Respond with any 2xx quickly. A non-2xx or a timeout is logged as a failed delivery — there's no retry queue yet, so don't do slow work before responding; queue it and respond first.

Verifying signatures

Same convention as Stripe and GitHub: recompute the HMAC yourself and compare.

const crypto = require('crypto');

function isValid(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody) // the raw, unparsed request body
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signatureHeader)
  );
}

Verify against the raw request body — parsing to JSON and re-serializing before hashing will produce a mismatch.

Event types

More event types (delivery receipts, flow-triggered events) are on the roadmap — the envelope shape above is designed so handling a new one is just a new event switch case, not a new integration.