Test channel: try your app without real customers

Last updated: 11 November 2026 · 6 min read

Steps

1. 1

   Create the test channel

   Open the “Test channel” section in the portal and press “Create test channel” next to the workspace. Only an administrator of that workspace can do this, and a workspace has one test channel. An API channel named “Developer test channel” appears in the workspace. If you like, demo conversations are added too: they send no notifications to the team and do not trigger automations. The channel shows in the dashboard like any other inbox: you can open it, read the messages and reply.

2. 2

   Send a customer message

   POST /v1/test_channel/messages writes a message to the test channel as a customer. The message is handled like a real incoming one: webhooks, the event feed, sync and automation all see it.

   • content: message text, at most 5000 characters.
   • conversation_id: optional, the number of a conversation in the test channel. The message goes into that conversation.
   • contact: optional, { "name", "identifier" }. A new conversation starts. The contact is the test channel's own contact with this identifier. If there is none, it is created.

   curl -X POST https://api.clomni.ai/v1/test_channel/messages \
     -H "Authorization: Bearer $CLOMNI_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"content": "Hi, where is my order?", "contact": {"name": "Test customer", "identifier": "crm-1001"}}'

   The response is 201 with the message in the sync shape. If the workspace has no test channel, you get 404 test_channel_missing. The old address /v1/sandbox/messages also works.

3. 3

   Which token you need

   The token needs messages:send or conversations:write. These two scopes work on the test channel before review too:

   1. Add messages:send or conversations:write to the app. There is no need to wait for review.
   2. Create a token in the “Credentials” section and choose that scope.
   3. The token can write customer messages to the test channel. For the rest of the workspace's data, only approved scopes work.

   To try a public app before its review, connect it in the app's own workspace as its owner: that workspace needs a test channel. Scopes that are not approved work there on the test channel only, too.

4. 4

   Nothing goes outside

   • The test channel has no webhook address, and setting one returns 403 test_channel_webhook. An agent's reply does not leave Clomni.
   • A simulated contact gets a name only: no email or phone, so no campaign or email reaches it.
   • The message lands in the test channel only. A conversation number from another inbox returns 404.

   The workspace's own webhooks and automations, and your app's webhook, see these messages as real ones. If your automation rule sends a message to the customer, that message also stays in the test channel's conversation.

5. 5

   Delete the test channel

   Press “Delete test channel” in the portal. The channel and its conversations are deleted in the background, the same as when an inbox is deleted in the dashboard. You can create a new one afterwards.

6. 6

   Old sandbox workspace

   Separate sandbox workspaces created before 9 November 2026 keep working: their tokens start with clomni_pat_test_, /v1/me returns workspace.sandbox: true, and actions that send anything outside return 403 sandbox_restricted. In the dashboard such a workspace shows the bar “This is a sandbox: test data, nothing reaches a real customer.” No new ones are created, and you can delete an old one on the portal's “Test channel” page.