Imported Channels (Not Connected)
When you migrate to SendSeven from another provider, the import can bring over conversations from numbers, email addresses and accounts that are not connected to SendSeven yet. SendSeven keeps that history on an imported channel: a channel that carries the real number, address or account, but has no connection yet.
An imported channel:
- shows its imported conversations and contacts like any other channel,
- cannot send messages and cannot be edited or tested,
- is not billed and does not count as a connected channel,
- becomes your live channel, with all its history, as soon as you connect the same number, address or account.
In the channel API
GET /api/v1/channels and GET /api/v1/channels/{channel_id} return imported channels with two extra fields (present on every channel):
| Field | Type | Meaning |
|---|---|---|
is_import_placeholder | boolean | true for an imported channel that is not connected yet |
connection_state | "connected" | "not_connected" | not_connected for an imported channel, connected for every other channel |
GET /api/v1/channels/{channel_id} also returns imported_conversation_count for an imported channel: the number of conversations it holds. It is null in the list and for every other channel.
Email and name-only imported channels
Imported channels exist for WhatsApp, SMS, email, Instagram and Messenger. An email imported channel carries the imported email address as its identifier.
When the old provider gave only a display name for an Instagram or Messenger account, and no account ID, the import creates a name-only imported channel: it has a name but its identifier cannot be matched to a real account. Connecting an account does not pick it up automatically. Name it explicitly with adopt_channel_id (see Connecting an imported channel).
An imported channel also has is_active: false and is_verified: false. needs_reconnect_reason is null: there is nothing to reconnect, the channel was never connected.
connection_state: "connected" does not mean the channel can send right now. For that, check availability.state, needs_reconnect_reason and setup_pending_reason as before.
{
"id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"channel_type": "whatsapp",
"name": "Support line",
"identifier": "4915112345678",
"phone_number_formatted": "+4915112345678",
"is_active": false,
"is_verified": false,
"is_import_placeholder": true,
"connection_state": "not_connected",
"needs_reconnect_reason": null
}
Calls that need a connection
These calls answer 409 with error channel_not_connected for an imported channel:
PUT /api/v1/channels/{channel_id}POST /api/v1/channels/{channel_id}/refresh-webhookandPOST /api/v1/channels/{channel_id}/health-check- profile, profile photo, WhatsApp username and WhatsApp phone registration calls under
/api/v1/channels/{channel_id}/... - Instagram media and Facebook Page post listings for the channel
- sending from the channel (messages, templates, campaigns, scheduled sends) when the endpoint checks the channel before sending
{
"detail": {
"error": "channel_not_connected",
"message": "This channel holds imported history and is not connected yet. ...",
"channel_id": "a1b2c3d4-5678-9abc-def0-1234567890ab"
}
}
Send endpoints return the same body shape as CHANNEL_DISCONNECTED (with reason: "import_placeholder" and reconnect_required: false). Some send paths may still answer CHANNEL_DISCONNECTED for an imported channel; treat both as "this channel cannot send".
Listing and reading an imported channel work as usual.
Deleting an imported channel
Deleting an imported channel that still holds imported conversations needs an explicit confirmation. Without it, DELETE /api/v1/channels/{channel_id} answers 409:
{
"detail": {
"error": "channel_has_imported_history",
"message": "This channel holds 42 imported conversations. Repeat the request with confirm=true to delete it anyway.",
"channel_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"conversation_count": 42
}
}
Send DELETE /api/v1/channels/{channel_id}?confirm=true to delete it anyway. An imported channel without conversations is deleted without confirmation.
Connecting an imported channel
Connect the same number, email address or account, in Settings > Connected Channels or through the API. What happens depends on the channel type:
- WhatsApp, Instagram and Messenger: SendSeven turns the imported channel into the live channel. The channel
idstays the same, the imported conversations stay on it,is_import_placeholderbecomesfalseandconnection_statebecomesconnected. - SMS and email: the newly connected channel or mailbox gets its own
id. SendSeven moves the imported history onto it and archives the imported channel.
An email imported channel is picked up automatically when you connect a mailbox with the same address. Billing for the channel starts once it is connected.
Choosing the imported channel explicitly (adopt_channel_id)
Pass adopt_channel_id, the id of an imported channel, to tell SendSeven which imported channel a new connection should take over. Use it for name-only imported channels, or when the connected number, address or account is written differently from the imported one. Without it, SendSeven matches by number, address or account.
| Endpoint | Where | Notes |
|---|---|---|
POST /api/v1/channels | request body | Not for email channels: an adopt_channel_id with channel_type email answers 422. |
POST /api/v1/email-integrations | request body | Moves the imported email history into the new mailbox's inbox. |
{
"channel_type": "whatsapp",
"name": "Support line",
"identifier": "4915112345678",
"adopt_channel_id": "a1b2c3d4-5678-9abc-def0-1234567890ab"
}
The connect flows in the SendSeven app (WhatsApp, Facebook Messenger, Instagram, SMS number provisioning and Gmail) accept the same option. They are not part of the public API.
Errors
| Status | error | When |
|---|---|---|
422 | invalid_adopt_channel | The id is not an imported channel (is_import_placeholder: true) of this workspace with the same channel type. The id you sent is not repeated in the response. |
409 | channel_identifier_taken | Another channel of this workspace already uses the connected number or account. The imported channel is left unchanged. Email connections never answer this error. |
{
"detail": {
"error": "invalid_adopt_channel",
"code": "invalid_adopt_channel",
"message": "The selected channel cannot be connected here. Choose a not-connected channel of this workspace with the same channel type."
}
}
Migrations that create imported channels
Migrations are started in the SendSeven app under Settings > Migration Tools. Creating imported channels during a migration needs the channels:create permission, and bringing back an earlier deleted channel with the same number or account also needs channels:delete.