Blueticked Conversations API

openapi: 3.2.0
info:
  title: Blueticked Conversations API
  version: 1.0.0
  description: 'Multi-channel messaging (WhatsApp, SMS, email), templates, flows, campaigns, per-recipient documents and webhooks for South African businesses, plus contacts, flows, AI agents, journeys, published sites and a commerce layer with products, orders and checkout. One send endpoint (`POST /api/v1/messages`) covers all three channels. See the request examples for the WhatsApp template, SMS, and email shapes. Authenticate every request with `Authorization: Bearer blu_live_...` (or `blu_test_...` for the sandbox). Send an `Idempotency-Key` header on the POSTs that honour it (the ones whose OpenAPI operation declares the `Idempotency-Key` parameter), and a retry of the same key replays the original response instead of repeating the write. Everywhere else the header is IGNORED, so a blind retry of a 5xx can create a second record. 29 of 48 documented POST operations deduplicate; the rest do not. ## Test mode


    Keys prefixed `blu_test_` are sandbox keys: sends never reach providers,

    never bill, and have their delivery lifecycle simulated (queued → sent →

    delivered → read, ~5s per step). Webhook deliveries fire with `"test": true`. Separately, a `test_mode: true` field on a send is a dry run that validates the

    request and returns `status: "validated"` without creating or sending anything;

    it works with any key, including a live one. Deterministic magic numbers:


    | Number | Behaviour |

    |---|---|

    | +27800000001 | Always delivers (any other number behaves the same) |

    | +27800000002 | Fails at the send step with `recipient_unreachable` |

    | +27800000003 | Delivers, then fires a simulated `message.received` reply |


    A test key''s writes are real workspace data: a contact it creates is stored like any other, where a live

    campaign could reach it. A live key refuses to send to the sandbox numbers (+27800000000 to +27800000099)

    from `POST /api/v1/messages` with 400 `validation_failed`, but a campaign or a flow does not check

    the number, so delete test contacts when you go live. ## Error codes


    | Code | Meaning |

    |---|---|

    | `invalid_field_map` | The inbound field map has an unknown or ambiguous target or repeats a contact identity target. |

    | `unauthorized` | The credential was refused: a missing or malformed Authorization header, an unknown key or a wrong secret, a revoked or expired key, an expired or revoked OAuth token, or an inactive workspace. Once a key''s secret checks out, details.reason says which (revoked, expired, workspace_inactive). |

    | `forbidden` | The credential is valid but not allowed here: a missing scope (details.required), an address outside the key''s IP allowlist, a business-restricted key on an endpoint it cannot use, or a blu_pub_ key off the agent chat endpoint or its allowed origins. |

    | `not_found` | The requested contact, template, message or campaign does not exist. |

    | `validation_failed` | The request was refused before anything happened. Either the body does not fit the schema (details is the list of schema issues, each with the field''s path), or a value breaks a rule (details names the field). |

    | `rate_limited` | The workspace or key exceeded a rate limit, or the calling address made too many failed authentication attempts. Wait Retry-After seconds, then retry. |

    | `idempotency_conflict` | The same Idempotency-Key was reused with a different body. |

    | `idempotency_in_progress` | A request with the same Idempotency-Key is still being processed; retry once it finishes. |

    | `resource_in_use` | The resource cannot be deleted because other live resources still depend on it (e.g. a group targeted by a scheduled campaign). `details` lists the dependents. |

    | `conflict` | The other kind of 409: the request collides with what already exists (a code or name that is taken, or a resource in a state the call does not accept, as when only a paid order can book a courier).'
  contact:
    name: Blueticked Developer Support
    url: https://blueticked.com/docs
    email: developers@blueticked.com
servers:
- url: https://app.blueticked.com
  description: Production
security:
- bearerAuth: []
tags:


# --- truncated at 32 KB (57 KB total) ---
# Full source: https://artifacts.apis.io/blueticked-com/openapi/blueticked-com-conversations-api-openapi.yml