Connect a Voiceflow assistant to COLVO

1 · Before you start

You need a Voiceflow project that handles billing conversations and its Dialog API key (Voiceflow → Integrations → Dialog API; it starts with VF.DM.). Remove any direct Stripe calls from the project.

2 · Add the colvo_propose API tool

In the agent, under Tools, add an API tool named colvo_propose. Trigger: “Use when the customer asks for a refund or to cancel a subscription, after finding the payment or subscription in the account context.” Add the inputs listed below with their descriptions — the model fills them from the conversation. Describe colvo_agent_key as “copy exactly from the COLVO line under the customer’s message”: COLVO writes that line, with a key that works for this test only and can only propose. Then, on the Agent tab, add colvo_propose under Global tools — a tool the agent doesn’t have is never called.

Tool (API) "colvo_propose" — inputs the agent fills:
  action           "refund", "cancel", "pause", "resume", "undo cancel", "change plan" or "coupon"
  payment_id       refunds: the payment id (pi_…) from the account context
  amount_minor     refunds: amount in cents, e.g. 5000 for €50
  currency         refunds: the payment's currency, e.g. eur
  subscription_id  cancellations: the subscription id (sub_…)
  mode             cancellations: "period_end" or "immediate"
  resumes_at       pauses: the date billing restarts, e.g. 2026-12-12 (leave empty if the customer gave no date)
  price_id         plan changes: the new plan's price id from the account context
  at               plan changes: "now" or "period_end"
  coupon_id        coupons: the coupon id from the account context
  invoice_id       refunds of older payments: the invoice id (in_…) instead of payment_id
  colvo_agent_key  copy exactly from the COLVO line under the customer's message

POST https://colvo.app/v1/operations
Authorization: Bearer {colvo_agent_key}
Content-Type: application/json

{ "action": "{action}",
  "parameters": { "payment_id": "{payment_id}", "amount_minor": "{amount_minor}", "currency": "{currency}",
                  "subscription_id": "{subscription_id}", "mode": "{mode}", "resumes_at": "{resumes_at}",
                  "price_id": "{price_id}", "at": "{at}", "coupon_id": "{coupon_id}", "invoice_id": "{invoice_id}" } }

One tool covers every action: empty inputs are ignored, "refund", "cancel", "pause", "resume" and "undo cancel" are understood, and an amount written as text ("5000") is read as a number.

3 · Tell the agent when to act

Add to the agent’s goal: use colvo_propose for refunds and cancellations, and only say “done” when it returns ALLOW; on REVIEW say a colleague will confirm; on DENY say it can’t be done here. Then Publish.

4 · Connect it in COLVO

Project → Connect your agent → Voiceflow. Paste the Dialog API key and choose production (published) or development. Keep “account facts” on — that is where the COLVO line comes from. Press Test connection.

5 · Run the suite

Press Run suite. Each test is a fresh Voiceflow user, so state never carries over. Each test uses a few Voiceflow messages — on the free plan, run one or two scenarios at a time. Next: read the verdict.