What is idempotency?

In one sentence

Idempotency means that doing the same thing twice has the same result as doing it once, so if a message is sent with the same reference number again, it is recognised as a repeat and not sent a second time. It is what lets an AI agent safely retry a message after a dropped connection or a busy moment without your customer receiving duplicates.

In more detail

Think of a lift button. Pressing it once calls the lift. Pressing it five more times does not call five more lifts; the lift is already coming. The button is idempotent: extra presses change nothing.

Sending a message is not naturally like that. If an agent asks for a message to be sent and the connection drops before the answer comes back, the agent cannot tell whether the message went out. If it simply tries again, the customer might get the same message twice. If it does not try again, the customer might get nothing.

Idempotency solves this with a reference number. Before the agent sends a message, it gives that message a unique label, often called an idempotency key. If the same label arrives again, the system recognises it: "I have already handled this one", and returns the original result instead of sending again.

The label belongs to one message, not to a customer or a chat. A brand-new message gets a brand-new label. A retry of the same message keeps the old label. That is the whole trick, and it means the agent can retry as often as it needs to without risk of doubling up.

Your customers never see any of this. They simply get one reply, even on a day when the internet is patchy or a platform is slow. The table below shows what happens on such a day, with and without a reference number. Names and details are examples.

An example

Why duplicates matter more than they seem

A repeated message can look like a small glitch. For a business, it is more than that.

• It looks careless. A customer who gets the same reply twice wonders whether anyone is paying attention.
• It can confuse. Two booking confirmations can make someone think they booked twice, or that something went wrong.
• It counts against your limits. Every message, duplicate or not, uses part of the account's daily allowance.
• It looks like a bot. Platforms watch for the same text sent again and again, and duplicates add to that pattern.
• It can cost money. Where actions are counted or billed, a duplicate is a wasted action.

When retries happen

Retries are normal and healthy. They happen in situations like these:

The rule is easy to remember: same message, same number; new message, new number.

What a reference number looks like

You will rarely need to see one, but here is a simplified example of a message request with its label. Names and details are examples.

Send a reply
  account:  Riverside Bistro WhatsApp
  chat:     Tom Harris
  text:     "Your table for four is booked for 7pm on Friday. See you then!"
  idempotency key: booking-reply-tom-2026-11-14

A good label is unique to that one message. Many agents make one from the job and the person, as above, or use a long random code. Either works, as long as a retry reuses it and a new message never does.

What if the same number is used for a different message?

This is the one mistake idempotency guards against in the other direction. If an agent reuses a label from an earlier message for a new, different message, a careful system refuses it rather than guessing. Sending the new text would break the promise that a label means one message; quietly ignoring it would lose the new message.

When that happens, nothing is sent and the agent is told the label was already used for something else. The fix is simple: give the new message its own label and send it again.

Common mistakes

• Making a new reference number on every attempt. That defeats the point, because each retry looks like a new message.
• Reusing one number for a whole batch. Each message in a batch needs its own label.
• Retrying too fast. A retry should wait, especially when the system says how long to wait.
• Not retrying at all. Without a retry, a message lost to a dropped connection simply never arrives.
• Assuming a duplicate webhook is a new event. Notifications can be delivered twice too, and each one carries an id so the receiving side can spot a repeat.

Questions to ask before you trust a tool to send for you

You do not need to read code to check whether a messaging tool protects you from duplicates. These plain questions are enough, and a good provider will answer them clearly.

1. If my agent sends the same message twice by accident, will the customer get it twice?
2. If a send is held back at a limit, is anything sent, and how does my agent know when to try again?
3. If the platform does not answer in time, can my agent retry safely?
4. If the same notification reaches my other tools twice, can they tell it is a repeat?
5. If I approve a held message, can approving it twice send it twice?

If the answers are "no", "nothing is sent, and it is told how long to wait", "yes", "yes" and "no", the tool handles idempotency well.

Why it matters for your business

• Customers get one reply, not two, even on days when connections are unreliable.
• Your sending limits are spent on real messages, not accidental repeats.
• Your accounts avoid the repeated-text pattern that platforms treat as a warning sign.
• Your agent can retry freely after a problem, so messages are not lost either.
• Bookings, orders and confirmations stay clear, with no doubled messages to explain.

How Spaces handles it

Every send through Spaces needs a reference number, which Spaces calls an Idempotency-Key. That covers replies, new chats and every other write. If the same key arrives again for the same message, Spaces recognises the repeat and does not send it twice. If the same key arrives with a different message, Spaces refuses it and sends nothing, so the agent can fix the label.

This is what makes Spaces' safety limits gentle on your customers. When an account is at a limit, or a platform does not answer in time, nothing is sent and the agent is told to try again later. It retries with the same key, and the message goes out once when it can. A reply held for your approval keeps its key too, so the same request returns the same waiting draft rather than a second one.

Webhooks from Spaces carry an event id. If the same event is delivered again, perhaps because your receiving tool did not confirm the first one, it is the same event and not a second message, so your tools can safely ignore the repeat. You do not need to set any of this up yourself; AI agents that follow the Spaces guide handle it for you.

In short

Idempotency means a repeat changes nothing. Give each message one reference number, reuse it when you retry, and the customer receives that message once.

It is invisible when it works, which is exactly how it should be. If you are choosing a tool that lets AI send messages for your business, it is worth checking that it works this way.

Do I need to understand idempotency to use an AI agent?

No. It is handled between your agent and the service it sends through. It helps to know it exists, so you can ask whether a tool protects you from duplicate messages.

What is an idempotency key?

It is a unique label, like a reference number, attached to one message. If the same label arrives again, the system knows it is a repeat and does not send the message a second time.

Why would my agent send the same message twice?

Usually because a connection dropped or a platform was slow, so the agent could not tell whether the first attempt worked. Retrying is right; the reference number makes the retry safe.

What happens if two different messages use the same key?

In Spaces, the second one is refused and nothing is sent. The agent gives the new message its own key and sends it again.

Does a held message still go out once I approve it?

Yes, once. The approved message goes through the normal route with the same key, so approving it cannot create a duplicate.

Can a webhook be delivered twice?

It can, if the first delivery was not confirmed. Each Spaces event has an id, so your receiving tool can treat a repeat as the same event rather than a new one.

How long should an agent wait before retrying?

As long as it is told. When Spaces holds a message at a limit, it says how many seconds to wait, and the agent should retry after that with the same key.

Is idempotency only about messages?

No. The same idea is used for payments, orders and bookings, anywhere doing something twice by accident would cause a problem.