Sending documents from your own system

What this does

Your assistant can look something up for a customer, let them choose, and then send them the actual file — an invoice PDF, a quotation, a delivery note — as a WhatsApp attachment.

The file comes from your system, not ours. You point K-Message at one of your own endpoints, describe when the assistant should use it, and the assistant does the rest.

Two things it deliberately does not do: it never sends a link instead of the file, and it never lets the assistant decide where to fetch from. The address and the credentials are yours, saved once. The assistant only ever chooses which record.

Setting one up

Go to Chatbot → AI Contexts → New, and pick Send a document as the type.

The action

Short name — how the action is identified internally, e.g. invoice_pdf. Lower-case letters, numbers and underscores.

When should the assistant use this? — the most important field. This is what the assistant reads when deciding whether to call it. Be explicit about what it must not do:

Send the customer a PDF copy of one of their own invoices. Use it only after listing their invoices, with an id copied exactly from that list. Never invent an id, and never say the document was sent before this action returns successfully.

What the assistant must supply — usually one input: the id of the record the customer picked. Give it a name (invoice_id), a description the assistant will read, and optionally a pattern like [0-9]{1,12} to reject anything that isn’t an id.

The endpoint

API URL — your endpoint, with placeholders:

https://erp.example.com/api/invoice/pdf?invoice_id={{args.invoice_id}}&mobile={{phone_number}}

Two kinds of placeholder are available, and only these two:

Placeholder	Comes from
{{phone_number}}	The customer in the conversation. Not something the assistant can choose.
{{args.your_input}}	An input you declared above, supplied by the assistant.

Headers — where your token goes. Saved encrypted and shown as *** afterwards; leave the *** in place when editing and your saved token is kept.

Where the file link is in the response — if your endpoint returns JSON containing a link, give the path to it, e.g. data.pdf_url. If your endpoint returns the file itself, leave this empty.

File name — what the customer sees, e.g. invoice-{{args.invoice_id}}.pdf.

Example: invoices from an ERP

Given an endpoint that answers

{ "ok": true, "data": { "pdf_url": "https://erp.example.com/files/1269104?token=0BnJ8g…" } }

configure:

Field	Value
Short name	invoice_pdf
Input	invoice_id, pattern [0-9]{1,12}, required
API URL	https://erp.example.com/api/invoice/pdf?invoice_id={{args.invoice_id}}&mobile={{phone_number}}
Headers	{"Authorization": "Bearer …"}
File link path	data.pdf_url
File name	invoice-{{args.invoice_id}}.pdf

Pair it with a lookup tool that lists the customer’s invoices, and the whole conversation works: the customer asks about a bill, the assistant lists them, the customer picks one, and the PDF arrives.

Sending several at once

Customers do not only ask for one. “Send me all of them” is the next thing they say, and doing it naively is the fastest way to hurt the system the documents come from: ten invoices means ten PDF renders back to back, and most ERPs render each one from scratch.

Switch on Send several at once and the assistant gets a second action alongside the first. Instead of fetching anything, it queues the documents and answers immediately with how long they will take. They are then delivered one at a time, in the background, spaced by the gap you set — and never more than one document per company at a time, however many customers are asking.

Setting	Meaning
Which input carries the list	One of the inputs you declared above, e.g. invoice_id. The assistant passes several values for that one; everything else stays a single value.
Most per request	1 to 50, twenty by default. Beyond this the assistant is told to ask the customer to narrow it down.
Seconds between documents	5 to 600, twenty by default. This is the pacing: five invoices at twenty seconds take a minute and forty seconds.

The assistant is told the documents arrive gradually and is given the number of minutes, so it can set the customer’s expectation instead of saying “sent” and leaving them wondering.

Note

The hourly per-customer limit on single sends does not apply to a queued batch — a ten-invoice request would otherwise stop after the fifth. What bounds it instead is the queue: at most 50 documents outstanding for one customer, and 500 for the whole company.

When something goes wrong

A document that fails is retried twice, after one minute and then five, before it is given up on. A document whose tool has since been deleted or switched off is not retried at all.

Chatbot → AI settings shows the queue: what is waiting, what was sent, what failed and why. It is worth a look the first time you switch batching on, and it is the place to check when a customer says they only received some of what they asked for. Finished entries are kept for a week.

What we check before sending

Because this fetches from an address you control and sends the result to your customer, every response is checked before it leaves:

• The bytes must match the file type. An HTML error page served with a 200 OK is rejected rather than delivered to the customer as their invoice.
• The file must be under 16 MB, and an oversize file is rejected outright — never truncated, because a truncated PDF uploads successfully and only fails later, silently.
• Redirects are re-checked at every hop, limited to three, and your token is dropped the moment a redirect crosses to a different host.
• Internal addresses are refused at save time and again when connecting.
• The assistant’s input is restricted to a narrow set of characters, so it cannot alter the address it is calling.
• Each customer can receive at most 5 documents an hour, since every send is a paid WhatsApp message.

Note

The response body from your endpoint is never shown to the assistant — only whether the send succeeded. That means nothing in your API’s output can change how the assistant behaves, and no customer data from it is stored in the conversation log.

Keeping a copy

By default the document is delivered to the customer but not stored in K-Message, so your agents cannot reopen it later. Switch on Keep a copy in the inbox if your agents need to see exactly what was sent — useful when a customer disputes an amount. It does mean customer documents are stored here as well as in your own system, so it is off unless you choose it.

Permissions

Creating or editing a document tool requires the chatbot settings write permission, because it configures an outbound call carrying your credentials. Ordinary knowledge contexts are unaffected.