Skip to content

Sendbird#

Sendbird is registered for read-only Sendbird Desk ticket sync with sync-coupled user import. An organization supplies the Application ID and a dedicated Desk API key for one Desk application. The adapter imports the current non-closed support queue into a reviewable TeamBoost import session; it does not import arbitrary Sendbird Chat conversations.

Capability Method Status
SYNC Pull current Desk tickets through Desk Platform API v1 Built
USER_IMPORT Bring active Desk agents and referenced ticket customers into task-import mapping Built as part of API sync
CSV_IMPORT Upload a Sendbird Desk report export Not built
WEBHOOK Receive Desk ticket events Not built

The endpoints below live under /api/v1/providers/sendbird/.... They are the generic provider endpoints and require an organization-scoped user token; see Authentication.

Discovery#

GET /api/v1/providers/sendbird

{
  "status": "success",
  "data": { "provider": "sendbird", "capabilities": ["SYNC", "USER_IMPORT"] }
}

Desk Setup And Credential Verification#

In Sendbird Dashboard, select the Desk application, then:

  1. Copy the case-sensitive Application ID from Settings > Application > General.
  2. Generate a dedicated key under Settings > Desk > Credentials.
  3. Store the key in a password manager. Do not place it in browser code, source, fixtures, logs, or a URL.

Store one strict versioned credential envelope per TeamBoost organization:

PUT /api/v1/providers/sendbird/credentials?organization_id=<id>
POST /api/v1/providers/sendbird/credentials/verify?organization_id=<id>

The write-only outer request contains a JSON-serialized secret:

{
  "secret": "{\"version\":1,\"applicationId\":\"YOUR_APPLICATION_ID\",\"deskApiKey\":\"YOUR_DEDICATED_DESK_KEY\"}"
}

The inner envelope accepts exactly version, applicationId, and deskApiKey. version must be 1; extra fields, blank values, malformed JSON, control characters, arbitrary URLs, and invalid Application IDs are rejected. The adapter constructs only this origin:

https://desk-api-{applicationId}.sendbird.com/platform/v1

Verification makes bounded read-only probes to both /agents and /tickets. Malformed or rejected credentials return invalid_api_key; transient provider or response-contract failures return service_unavailable. Stored secrets are encrypted at rest, scoped to one TeamBoost organization, replaceable through the same PUT, and never returned by the API.

Importing Desk Tickets#

POST /api/v1/providers/sendbird/imports/sync?organization_id=<id>

The adapter sends the Desk key only in SENDBIRDDESKAPITOKEN. It reads the agent directory and tickets in these current, non-closed states:

  • INITIALIZED
  • PROACTIVE
  • PENDING
  • ACTIVE
  • WORK_IN_PROGRESS
  • IDLE

The pull is bounded to 500 records per page and 5,000 agents plus 5,000 tickets per sync. Pagination must advance on the fixed Sendbird origin. Repeated, decreasing, cross-origin, inconsistent, or over-limit pagination fails the whole sync instead of persisting a partial import. Network and 5xx failures use at most three attempts; a valid bounded Retry-After is honored for 429, while deterministic 4xx responses are not retried.

A valid empty queue produces an empty reviewable session rather than an authentication failure. Closed-ticket history is not fetched.

User Mapping#

USER_IMPORT rides the ticket sync; there is no standalone user-import route. The adapter imports active Desk agents using agent:<id> and customers referenced by the bounded ticket set using customer:<id>. The namespaces keep agent and customer numeric identifiers distinct.

Agent and syntactically valid requester e-mail addresses can exact-match a TeamBoost organization member. Names remain review hints. A mapped assigned agent becomes the proposed ownerId; an assigned-but-unmapped agent creates a blocking projection error. An unassigned ticket keeps ownerId unset. A mapped customer becomes both creatorId and requestedById; otherwise both remain unset with a mapping note until TeamBoost's upstream task-execution contract supplies its reserved system creator.

Desk bots

The current adapter does not have a proven Desk bot discriminator. Do not use this sync in an application with active Desk bots until bot-agent exclusion has been validated and documented.

Projection Field Coverage#

Sendbird Desk source TeamBoost draft field Notes
Ticket channelName title Fewer than two usable characters is a projection error
Desk ticket type Defaults to OTHER with a mapping note
priority priority LOW, MEDIUM, HIGH, and URGENT map directly; other values become UNKNOWN
INITIALIZED, PENDING status NOT_STARTED
ACTIVE, WORK_IN_PROGRESS status IN_PROGRESS
PROACTIVE, IDLE status, blockedReason BLOCKED, WAITING_FOR_CLIENT
Ticket tags labels Unique non-empty tag names
Mapped assigned agent ownerId Unmapped assignment blocks confirmation
Mapped customer creatorId, requestedById Both map to the customer member
Application ID projectTitle Sendbird Desk - <applicationId> with a mapping note
Desk team name taskGroupTitle Sendbird Desk - <team name> with a mapping note
Desk lifecycle scheduleStage Defaults to PENDING
Ticket/group/channel ids, raw status and priority, tags, custom fields, lifecycle timestamps, last-message summary, support metrics, related channels, and CSAT descriptionJson.sendbird Context only; support timings do not become task effort or dates

The import session retains a sanitized, snake-cased source record for authorized review. Opaque last-message payload/member blobs and photo-thumbnail URLs are removed. The adapter does not fetch or project a full message transcript.

Not Built Yet#

  • Arbitrary Sendbird Chat channels or messages.
  • Closed-ticket history or date-partitioned migration.
  • Full ticket transcripts and attachments.
  • CSV ticket import; Desk report CSVs are analytics rather than ticket records.
  • Standalone agent/customer directory import.
  • OAuth or a TeamBoost-managed Sendbird application install.
  • Desk webhooks, signature verification, replay protection, or deduplication.
  • Reliable active-bot exclusion.