conversations

Hand a conversation over to a teammate

Hand the lead of a one-to-one LinkedIn thread over to a teammate. LinkedIn adds nobody to a one-to-one, so the thread's sender profile opens a LinkedIn group with the lead and the teammate, and message is its first message. Name the teammate: to_sender_profile_sid for a sender profile here (the task goes to its user), to_target for anyone else (a link, slug or URN).

It leaves behind result.group (the new thread), result.message (the queued introduction; a failed one is sent again with retry_messages) and result.task (who goes on). The one-to-one thread (item) is closed; both get a handed_over pill naming the other; the AI SDR is off on every live thread of the lead (plans superseded, runs, drafts and queued sends canceled). A message in result.group goes out as the handing sender profile. Hand back: reopen the thread and clear agent_mode_override (update_conversation).

Refusals write nothing: 409 already_a_group (add_conversation_participants instead), stoplisted, no_linkedin_channel, lead_not_on_linkedin, lead_unresolvable, already_handed_over (context.group_conversation_sid), sender_profile_unknown, sender_unavailable; 422 on the field that named the teammate (teammate_is_lead, teammate_is_sender, teammate_has_no_linkedin, teammate_unresolvable, not_a_linkedin_profile, profile_unresolvable) or gtm_connection_not_active; 403 account_not_allowed, gtm_scope_missing; 429 gtm_busy or bucket_saturated, 503 gtm_unavailable or playtables_unavailable: try later.

Contract:

  • MCP tool hand_over_conversation, registry package mcp.unibox/conversations, mount unibox.inbox.
  • Operation action, response envelope action.
  • Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.
post/api/conversations/{sid}/hand-over

Request

  • Base URL
    https://beta.getsales.io/unibox/v1
  • Auth
    HTTP bearer and API key in header Team-SID

Path parameters

sidstring required

The one-to-one LinkedIn thread whose lead is handed over (is_group false, a LinkedIn channel on it).

Request body

to_sender_profile_sidstring

The teammate as a sender profile of this workspace (ub_sp_...) with a LinkedIn account, other than the sender profile the thread runs on. Exactly one of this and to_target.

to_targetstring

The teammate as a LinkedIn profile: a linkedin.com/in/, Sales Navigator or Recruiter link, a bare slug or a raw URN, resolved like resolve_conversation_counterpart. For a teammate with no sender profile; exactly one of this and to_sender_profile_sid.

messagestring required

The introduction: the first message of the group, sent by the thread's sender profile, read by the lead and the teammate. Say who joins and why, e.g. "Jody, adding our co-founder Peter: he works with our agency clients and takes it from here."

titlestring

A name for the LinkedIn group, max 100 chars; without one LinkedIn shows the members.

Response

action success envelope.

successtrue required
operation'action' required
actionstring required

kebab-case verb; matches the route segment.

Changes

No recorded changes to this operation across all 1 revision of this API.