n8n-nodes-genuka-inbox

n8n community nodes for Genuka — multi-channel messaging via the Genuka Inbox API (WhatsApp, SMS, Instagram, Telegram, Web) and customer CRM operations (notes & tags) via the Genuka Admin API. The main node is usableAsTool, so AI Agents in n8n can call it directly.

Nodes included

• Genuka Inbox — three resources:
  • Message — send to a recipient (creates a conversation if needed) or reply inside an existing conversation. Supports text, media (image/video/audio/voice/file/sticker/gif), location, contact, WhatsApp templates, internal notes and custom payloads.
  • Customer — find by phone, get, add tags, remove a tag, replace all tags.
  • Customer Note — create, update, list, get.
• Genuka Inbox Trigger — webhook trigger for message.received, message.status_updated, conversation.created, conversation.assigned, conversation.updated events. Verifies the X-Genuka-Signature HMAC.

Credentials

The node uses two credentials depending on the selected resource:

Genuka Inbox API (for Message)

An Inbox API token (iapi_live_…). Generate one in your Genuka dashboard under Inbox → Agents → API Tokens. Sent as Authorization: Bearer iapi_live_…. Companies are inferred from the token — no extra header needed.

Token scopes required depending on what you send:

• send_text — text & internal notes
• send_media — image, video, audio, voice_note, file, sticker, gif
• send_template — WhatsApp templates
• upload_media — when uploading files (not used by these nodes directly)

A token with * bypasses scope checks.

Genuka Admin API (for Customer and Customer Note)

A standard admin API key. Generate one in your Genuka dashboard under Settings → API Keys. Sent as X-API-Key: … with X-Company: <companyId> (required by admin endpoints). The credential form asks for:

• API Key
• Company ID (ULID)
• Base URL (override for self-hosted/staging)

Installation

Option 1 — Self-hosted n8n

cd ~/.n8n/custom
npm install n8n-nodes-genuka-inbox
# restart n8n

Or, in newer self-hosted n8n versions, add n8n-nodes-genuka-inbox to Settings → Community Nodes.

Option 2 — Local development

cd /path/to/n8n-genuka-nodes
npm install
npm run build
npm link

cd ~/.n8n/custom
npm link n8n-nodes-genuka-inbox
# restart n8n (n8n start)

Usage — Messaging

Send a text message via WhatsApp

1. Add a Genuka Inbox node.
2. Resource = Message, Operation = Send to Recipient.
3. Channel = WhatsApp, To = +237600000000.
4. Message Type = Text, Body = "Hello from n8n 👋".

Reply inside an existing conversation

1. Operation = Reply in Conversation.
2. Conversation ID = ULID of the conversation.
3. Pick a Message Type and fill the body.

Send a WhatsApp template

1. Message Type = WhatsApp Template.

2. Template Name = order_confirmation (must be approved in your WABA).

3. Language Code = fr.

4. Components = WhatsApp template components JSON, e.g.:

   [
     {
       "type": "body",
       "parameters": [
         { "type": "text", "text": "Wilfried" },
         { "type": "text", "text": "ORD-12345" }
       ]
     }
   ]

Custom message types (order, invoice, button_message, …)

Pick Message Type = Custom (Raw Content JSON) and put the canonical message type in __type:

{
  "__type": "button_message",
  "body": "Pick an option",
  "buttons": [
    { "id": "yes", "title": "Yes" },
    { "id": "no", "title": "No" }
  ]
}

The node strips __type and sends the rest as content.

Usage — Customers (admin API)

Find a customer by phone

1. Resource = Customer, Operation = Find by Phone.
2. Phone = +237600000000 (contains-style match).
3. Return = First Match Only (default) or All Matches (Paginated).

Get a customer

Resource = Customer, Operation = Get, Customer ID = ULID.

Add / replace / remove tags

• Add Tags — Resource = Customer, Operation = Add Tags. Tags = comma-separated names (e.g. vip, newsletter). Missing tags are created automatically.
• Replace Tags — same input as Add, but replaces the full tag set on the customer.
• Remove Tag — requires the Tag ID (call Get first to retrieve tag IDs).

Usage — Customer Notes

• Create — Customer ID + Content (+ optional Metadata JSON).
• Update — Customer ID + Note ID. Provide Content and/or Metadata. Fields left empty are untouched.
• List — Customer ID → returns notes for that customer.
• Get — Note ID.

Using the node as an AI-Agent tool

The node is declared with usableAsTool: true. In an n8n AI Agent workflow, attach it as a tool and let the model pick the right resource/operation. Typical flows:

• Agent receives a message → uses Customer: Find by Phone on the sender number → calls Customer Note: Create to log what the customer said → optionally Customer: Add Tags to categorize the customer.
• Agent needs to update its own understanding → Customer Note: List → Customer Note: Update on the relevant note.

Receiving events (Trigger)

1. Add a Genuka Inbox Trigger node and copy the production webhook URL.
2. In Genuka, go to Inbox → Agents, create or edit an agent and set:
   • Webhook URL = the n8n URL
   • Subscribed events = whichever ones you want (or none = all)
   • Webhook Secret = a long random string
3. Paste the same secret into the trigger's Webhook Secret field.
4. Activate the workflow.

The trigger emits one item per delivered event with the canonical Genuka payload:

{
  "event": "message.received",
  "agent_id": "01H…",
  "company_id": "01H…",
  "timestamp": "2026-04-20T12:00:00.000Z",
  "api_version": "2023-11",
  "data": { /* event-specific */ },
  "delivery_id": "01H…"
}

Requests with an invalid or missing signature (when a secret is configured) are rejected with HTTP 401.

API endpoints used

Inbox API (Inbox token):

• POST {baseUrl}/2023-11/inbox/messages — send to recipient
• POST {baseUrl}/2023-11/inbox/conversations/{conversationId}/messages — reply in conversation

Admin API (API key + X-Company):

• GET {baseUrl}/2023-11/admin/customers?filter[phone]=… — find by phone
• GET {baseUrl}/2023-11/admin/customers/{id} — get customer
• POST {baseUrl}/2023-11/admin/customers/{id}/tags — attach tags
• PUT {baseUrl}/2023-11/admin/customers/{id}/tags — replace tags
• DELETE {baseUrl}/2023-11/admin/customers/{id}/tags/{tagId} — detach tag
• POST {baseUrl}/2023-11/admin/customers/{id}/notes — create note
• PATCH {baseUrl}/2023-11/admin/customers/{id}/notes/{noteId} — update note
• GET {baseUrl}/2023-11/admin/customer-notes?filter[customer_id]=… — list notes
• GET {baseUrl}/2023-11/admin/customer-notes/{id} — get note

Default base URL: https://api.genuka.com. Override in the credential for self-hosted/staging.

License

MIT