Skip to main content
There are three kinds of keys, and each one has its own job. Two prove who you are when you call us. One proves it is really us when we call you.

​
Response URL token

Every event we send includes a response_url. The key is already part of the URL:
Do not send an Authorization header. Having the URL is your permission. This is why no-code tools are so easy here: map the field and POST to it.
​
Time to live
45 minutes
The clock starts when the event is created. Expired tokens return 410 RESPONSE_URL_EXPIRED.
​
Reuse
multi-use
Use it as many times as you like until it expires. Post several messages, or update one message many times.
​
Rate limit
30 requests / minute
Per token. Going over returns 429 with a retry_after value.
​
Scope
one conversation
The token only works for the conversation that created the event.
The token is signed, so we can check it without a database lookup. Retries of the same event reuse the same token.
Treat a response_url like a password. Anyone who has it can post into that conversation until it expires.

​
API key

For anything outside the 45-minute window — cron jobs, long tasks, or messages you start yourself — use a key. Create one in your bot’s settings.
​
Authorization
string
required
Bearer mac_live_…. Anything else returns 401 invalid_api_key.
How keys behave:
  • One key, one chatbot. A key cannot touch another bot’s conversations. Using it on the wrong bot’s files endpoint returns 403 wrong_chatbot.
  • Shown once. We only store a hashed copy, plus the last few characters so you can tell keys apart. If you lose it, make a new one.
  • Can be turned off. A revoked key stops working right away. You can also set a future end date, which gives you time to switch to a new key.
  • Rate limited to 120 writes per minute and 300 reads per minute, per key.
Keys belong on your server. Never put one in a browser, a mobile app, or a public repo. Anyone who has it can post as your bot.

​
Webhook signing secret

This one works the other way around: we sign every request we send you, and you check the signature.
Find it in your bot’s webhook settings. It signs the X-MyAIChatbot-Signature header on every POST we send, including retries and tests.
Checking it is not optional. Without the check, anyone who learns your webhook URL can pretend to be us. Full guide in five languages: Verifying signatures.
A new secret starts working right away. There is no overlap period, so deploy the new secret first, then rotate.

​
Which one do I need?

Replying to an event

Use the response_url. No key needed.

Starting a message later

Use an API key. It never expires.