Tool catalog

List the workspaces this token can act in, with the role and effective scopes it holds in each. Call this first, then pass a workspace subdomain to every other tool.

• workspaces array required
  each item: object

  • subdomain string required
  • name string required
  • role string required
  • scopes array required
    each item: string

Add a source that crawls a fixed list of URLs into a knowledge collection.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• collection_id integer required
• name string required
• urls any required

  Array of URLs, or a newline-separated string of URLs

• sync_frequency string optional one of manual daily weekly monthly

• source_id integer required
• name string required
• url_count integer required

Add a source that crawls an entire website into a knowledge collection.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• collection_id integer required
• name string required
• base_url string required
• max_pages integer optional
• sync_frequency string optional one of manual daily weekly monthly

• source_id integer required
• name string required
• base_url string required

Create a new knowledge collection in the workspace.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• name string required
• description string optional

• collection_id integer required
• name string required

Delete a knowledge document.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• document_id integer required

• document_id integer required
• deleted boolean required one of true

Delete a knowledge source and its documents.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• source_id integer required

• source_id integer required
• deleted boolean required one of true

Fetch the full text of one knowledge document by id.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• document_id integer required

• document_id integer required
• title string required
• content_type string required one of text markdown
• content string or null required

Get one knowledge source with its documents (one per page or file it brought in): url, title, status, the error a failed one hit, and when it last changed. Documents are paged with limit and offset.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• source_id integer required
• limit integer optional

  Documents per page, at most 200 (default 50).

• offset integer optional

• source object required
  • id integer required
  • collection_id integer required
  • name string required
  • type string required one of website url document

    website crawls a site from url; url fetches the listed urls; document holds uploaded files.

  • url string or null required

    Where a website source starts crawling; null for the other types.

  • urls array required

    The pages a url source fetches; empty for the other types.

    each item: string
  • status string required one of pending syncing active error

    pending until the first sync, syncing while one runs, active after one finished, error after one failed.

  • syncing boolean required

    Whether a sync holds the source right now.

  • sync_frequency string required one of manual daily weekly monthly
  • max_pages integer or null required

    The most pages a website source crawls; null for the other types.

  • last_synced_at string or null required

    When the last sync finished; null if none has.

  • document_count integer required
  • failed_document_count integer required

    Documents whose fetch or processing failed; knowledge.get_source gives each one's error.

  • created_at string required
  • updated_at string required
• documents array required
  each item: object

  • id integer required
  • url string or null required

    The page it came from; null for an uploaded file.

  • title string required
  • status string required one of pending processing processed error
  • error string or null required

    Why the document failed; null unless status is error.

  • processed_at string or null required
  • updated_at string required
• has_more boolean required

List the workspace's knowledge collections with how many sources and documents each holds. knowledge.search reads only active collections.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• limit integer optional
• offset integer optional

• collections array required
  each item: object

  • id integer required
  • name string required
  • description string or null required
  • status string required one of active archived
  • source_count integer required
  • document_count integer required
• has_more boolean required

List the workspace's knowledge sources, optionally for one collection: type, where it reads from, sync status and schedule, page cap, when it last synced, and how many documents it holds and how many failed. knowledge.get_source lists a source's documents.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• collection_id integer optional

  Only this collection's sources (knowledge.list_collections).

• limit integer optional
• offset integer optional

• sources array required
  each item: object

  • id integer required
  • collection_id integer required
  • name string required
  • type string required one of website url document

    website crawls a site from url; url fetches the listed urls; document holds uploaded files.

  • url string or null required

    Where a website source starts crawling; null for the other types.

  • urls array required

    The pages a url source fetches; empty for the other types.

    each item: string
  • status string required one of pending syncing active error

    pending until the first sync, syncing while one runs, active after one finished, error after one failed.

  • syncing boolean required

    Whether a sync holds the source right now.

  • sync_frequency string required one of manual daily weekly monthly
  • max_pages integer or null required

    The most pages a website source crawls; null for the other types.

  • last_synced_at string or null required

    When the last sync finished; null if none has.

  • document_count integer required
  • failed_document_count integer required

    Documents whose fetch or processing failed; knowledge.get_source gives each one's error.

  • created_at string required
  • updated_at string required
• has_more boolean required

Re-queue a knowledge document for processing and embedding.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• document_id integer required

• document_id integer required
• status string required one of pending processing processed error

Search the workspace knowledge base and return relevant passages. Searches every active collection unless collection_id or collection_ids narrows it.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• query string required
• limit integer optional
• collection_id integer optional

  Search only this collection (knowledge.list_collections).

• collection_ids array optional

  Search only these collections. Combines with collection_id.

  each item: integer

• results array required
  each item: object

  • document_id integer required
  • title string required
  • content string required
  • score number required

Trigger an immediate re-sync of a knowledge source.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• source_id integer required

• source_id integer required
• status string required one of pending syncing active error

Update a knowledge collection's name or description.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• collection_id integer required
• name string optional
• description string optional

• collection_id integer required
• name string required
• description string or null required

Add a column to a workspace storage table.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• table string required
• name string required
• type string required
• encrypted boolean optional

• table string required
• columns array required
  each item: object

  • name string required
  • type string required
  • encrypted boolean required

Delete several rows from a workspace storage table, by lookup key or a search term.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• table string required
• lookup_keys array optional
  each item: string
• search string optional

• deleted_count integer required

Change which columns identify a row in a workspace storage table, rebuilding every row's key.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• table string required
• key_columns array required
  each item: string

• table string required
• key_columns array required
  each item: string

Create a new workspace storage table, optionally with columns.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• name string required
• description string optional
• columns array optional
  each item: object

  • name string optional
  • type string optional
  • encrypted boolean optional

• table string required
• columns array required
  each item: object

  • name string required
  • type string required
  • encrypted boolean required

Delete a row from a workspace storage table, found by its lookup key.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• table string required
• lookup_key string required

• lookup_key string required
• deleted boolean required

Delete a workspace storage table and all of its rows.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• table string required

• table string required
• deleted boolean required

Drop a column from a workspace storage table.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• table string required
• column string required

• table string required
• columns array required
  each item: object

  • name string required
  • type string required

Insert a row into a workspace storage table from a map of column name to value.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• table string required
• values object required

• lookup_key string or null required
• row object required

List the workspace storage tables and their columns.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• limit integer optional
• offset integer optional

• tables array required
  each item: object

  • name string required
  • description string or null required
  • row_count integer required
  • columns array required
    each item: object

    • name string required
    • type string required
• has_more boolean required

Read rows from a workspace storage table, optionally filtered by a search term.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• table string required
• search string optional
• limit integer optional
• offset integer optional

• rows array required
  each item: object

  • lookup_key string or null required
• has_more boolean required

Rename a column on a workspace storage table.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• table string required
• column string required
• new_name string required

• table string required
• columns array required
  each item: object

  • name string required
  • type string required

Update a row in a workspace storage table, found by its lookup key.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• table string required
• lookup_key string required
• values object required

• lookup_key string or null required
• row object required

Update a workspace storage table's name or description.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• table string required
• name string optional
• description string optional

• table string required
• description string or null required

Apply an ordered batch of surgical edits (add_node, update_node, delete_node, connect, disconnect) to a flow graph, atomically. update_node takes dotted paths into the node that start with data. or position., such as data.message or data.agentSettings.personality.instructions. Reference or shape errors reject the whole batch and save nothing; a graph that saves but fails validation is returned with valid:false and errors. Warnings name teams, agents, members or categories a node points at that are not this workspace's (flow.list_routing_options and leads.list_categories list the valid ones).

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• definition_id integer required
• ops array required
  each item: one of

  add_node

  • op any required one of add_node
  • id string required
  • type string required
  • data object optional
  • position object optional
    • x number optional
    • y number optional

  update_node

  • op any required one of update_node
  • node_id string required
  • set object optional

    Dotted path to new value. Every path starts with data. or position., such as {"data.message": "Hi"} or {"data.agentSettings.personality.instructions": "..."}. Setting a path replaces the value there whole, arrays included.

  • unset array optional

    Dotted paths to remove, each starting with data. or position., such as data.inputConfig.validation.

    each item: string

  delete_node

  • op any required one of delete_node
  • node_id string required

  connect

  • op any required one of connect
  • source string required
  • target string required
  • source_handle string optional
  • target_handle string optional

  disconnect

  • op any required one of disconnect
  • edge_id string required

  disconnect

  • op any required one of disconnect
  • source string required
  • target string required
  • source_handle string optional
  • target_handle string optional

• applied array required
  each item: object

  • op string required
  • node_id string optional
  • edge_id string optional
  • edge_ids array optional
    each item: string
• status string required one of saved saved_with_errors
• valid boolean required
• error_summary string optional
• errors array required
  each item: string
• warnings array required

  Teams, agents, members or categories a node names that are not this workspace's. They do not block publishing but are ignored at run time.

  each item: string

Patch a deployment's platform_configuration with dotted set/unset paths, merged into the existing config and validated as a whole. Invalid config is refused and nothing is saved. Use flow.get_deployment to see the keys each platform expects. insights_on_handoff and insights_on_close (Insights at handoff and at close) are each off unless set to "1" and use the AI allowance.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• deployment_id integer required
• set object optional
• unset array optional

• deployment_id integer required
• serving boolean required
• platform_configuration object required

Create a new flow definition. Starts from a blank graph unless a template key is given (see flow.list_templates).

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• name string required
• description string optional
• template string optional
• personality string optional

• definition_id integer required
• name string required

Deploy a flow definition to a platform. Creating or activating a deployment on a connected platform (Intercom, WhatsApp, Telegram, Messenger, Instagram, X) triggers live side effects -- webhook setup, tag sync -- against that platform.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• definition_id integer required
• name string required
• platform string required
• version_strategy string optional
• deployed_version_id integer optional
• platform_connection_id integer optional
• active boolean optional
• support_team_id integer or null optional
• support_agent_id integer or null optional
• marketing_team_id integer or null optional
• lead_assignee_id integer or null optional

• deployment_id integer required
• serving boolean required

Delete a flow definition.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• definition_id integer required

• definition_id integer required
• deleted boolean required

Get a flow definition's graph (nodes and edges), publication status, and routing: who handles handoffs and follows up leads on every deployment that does not set its own.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• definition_id integer required

• id integer required
• name string required
• description string or null required
• data object required
  • nodes array required
  • edges array required
• publication_status string required
• can_publish boolean required
• latest_version_id integer or null required
• personality string required
• routing object required
  • support_team_id integer or null required
  • support_agent_id integer or null required
  • marketing_team_id integer or null required
  • lead_assignee_id integer or null required

Get one deployment's platform, status, version, connection, current platform_configuration and routing, plus per-platform config hints (which keys that platform expects) and the effective settings it runs with: test mode, whether an identity secret is set for signed-in visitors, and CSAT as the plan, the deployment's switch and the workspace's wording combine. Routing holds the deployment's own choices; a null falls back to the flow's routing (flow.get_definition).

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• deployment_id integer required

• id integer required
• name string required
• platform string required
• active boolean required
• serving boolean required
• version_strategy string required
• deployed_version_id integer or null required
• platform_connection object or null required
  • id integer required
  • platform string required
• platform_configuration object required
• routing object required
  • support_team_id integer or null required
  • support_agent_id integer or null required
  • marketing_team_id integer or null required
  • lead_assignee_id integer or null required
• effective object required
  • test_mode boolean required

    A test deployment, the one flow.run and the editor's test panel use.

  • identity_secret_set boolean required

    Whether the deployment has an identity secret for signing in visitors. The secret itself is never returned.

  • csat object required
    • enabled boolean required

      Whether conversations on this deployment get the satisfaction survey.

    • question string required
    • thank_you string required
    • reason string or null required one of test_deployment not_in_plan not_switched_on

      Why the survey is off: test_deployment (test deployments never survey), not_in_plan (the workspace's plan leaves it out), not_switched_on (the deployment has not turned it on). Null while it is on.

• config_hints object required
  • required array required
    each item: string
  • optional array required
    each item: string
  • notes object required

List the workspace's deployments, optionally for one definition: id, name, platform, active/serving, version strategy.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• definition_id integer optional

• deployments array required
  each item: object

  • id integer required
  • name string required
  • platform string required
  • active boolean required
  • serving boolean required
  • version_strategy string required
  • definition_id integer required

List the node types available for building a flow, with their fields and defaults.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

The choices for a flow's or deployment's routing: the teams that work on the inbox with their support agents (support_team_id), active support agents (support_agent_id), the teams that work on leads with their members holding an active marketing seat (marketing_team_id), and those members by membership id (lead_assignee_id).

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• support_teams array required
  each item: object

  • id integer required
  • name string required
  • agent_ids array required
    each item: integer
• support_agents array required
  each item: object

  • id integer required
  • name string required
• marketing_teams array required
  each item: object

  • id integer required
  • name string required
  • member_ids array required
    each item: integer
• members array required
  each item: object

  • id integer required
  • name string required

List the flow templates flow.create_definition can start from. Pass a template's key as create_definition's `template`.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

Publish a flow definition's current draft as a new version, feeding live deployments on the latest strategy.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• definition_id integer required
• notes string optional

• version_id integer required
• content_hash string required
• published_at string required

Restore a flow definition's draft to a prior version's graph.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• version_id integer required

• definition_id integer required
• restored boolean required

Send a message to your bot in test mode and get its reply. Pass conversation_ref to continue. Pass visitor to start the conversation as a webchat visitor your site signed in, so the flow sees @visitor.signed_in, @visitor.user_id and @visitor.verified_attributes.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• definition_id integer required
• message string required
• conversation_ref string optional
• visitor object optional

  Start the conversation as a signed-in webchat visitor, as if your site had signed them in with an identity token. Applies to a new conversation only: with conversation_ref it is ignored and the conversation keeps the visitor it started as. A new run as the same user_id ends that user's previous test conversation.

  • user_id string required

    Your user's id, read by the flow as @visitor.user_id.

  • name string optional
  • email string optional
  • phone string optional
  • attributes object optional

    Signed attributes, read as @visitor.verified_attributes.<key> and @visitor.attributes.<key>. Kept like a real identity token's: up to 25 keys of letters, digits, _ . or -, with string, number, boolean or null values; anything else is dropped.

• reply string or null required
• conversation_ref string required

Update a flow definition's name, description, bot personality, or routing (support_team_id, support_agent_id, marketing_team_id, lead_assignee_id; null clears, and flow.list_routing_options lists the choices). A deployment's own routing wins over the flow's. The graph is edited with flow.apply_graph_ops, not here.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• definition_id integer required
• name string optional
• description string optional
• personality string optional
• support_team_id integer or null optional
• support_agent_id integer or null optional
• marketing_team_id integer or null optional
• lead_assignee_id integer or null optional

• updated boolean required

Update a deployment: activate/deactivate it, change its version strategy or pinned version, rename it, or set its routing (support_team_id, support_agent_id, marketing_team_id, lead_assignee_id; null falls back to the flow's routing, and flow.list_routing_options lists the choices). Activating a deployment on a connected platform triggers live side effects. Use flow.configure_deployment for platform_configuration.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• deployment_id integer required
• name string optional
• active boolean optional
• version_strategy string optional
• deployed_version_id integer optional
• support_team_id integer or null optional
• support_agent_id integer or null optional
• marketing_team_id integer or null optional
• lead_assignee_id integer or null optional

• deployment_id integer required
• serving boolean required

Fetch one conversation's transcript and context (deployment, definition, contact). The transcript is null unless you are a workspace owner or admin. Add read:conversations_pii for the flow's collected variables, contact email/phone and the visitor's submitted PII.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer required

• transcript string or null required
• status string required
• platform string required
• test_mode boolean required
• started_at string or null required
• last_activity_at string or null required
• context object required
  • deployment object or null required
    • id integer required
    • name string or null required
    • platform string required
  • definition object or null required
    • id integer required
    • name string or null required
  • version object or null required
    • id integer required
    • content_hash string or null required
  • current_node_id string or null required
  • variables object optional
  • contact object or null required
    • name string required
    • verified boolean required
    • email string or null optional
    • phone string or null optional
  • user_info object optional

List conversations in the workspace, with optional filters. Mirrors the customer dashboard's conversation list.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• definition_id integer optional
• deployment_id integer optional
• status string optional
• platform string optional
• test_mode boolean optional
• limit integer optional
• offset integer optional

• conversations array required
  each item: object

  • id integer required
  • session_id string required
  • status string required
  • platform string required
  • test_mode boolean required
  • deployment_id integer or null required
  • definition_id integer or null required
  • started_at string or null required
  • last_activity_at string or null required
  • message_count integer required
  • contact object optional
    • name string required
    • email string or null optional
    • phone string or null optional
• has_more boolean required

Fetch the ordered node-execution trace and AI usage summary for one conversation, for debugging a flow run (including test-mode runs from flow.run).

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer required
• limit integer optional
• offset integer optional

• steps array required
  each item: object

  • step_id integer required
  • processing_time_ms integer or null required
  • node_executions array required
    each item: object

    • node_id string required
    • node_label string required
    • node_type string required
    • execution_order integer required
    • processing_time_ms integer or null required
    • outgoing_handle string or null required
    • input_data object or null required
    • output_data object or null required
    • metadata object or null required
    • agent_executions array required
      each item: object

      • provider string required
      • model_id string required
      • status string or null required
      • input_tokens integer or null required
      • output_tokens integer or null required
      • cost number required
      • duration_seconds number or null required
      • error_message string or null required
    • rag_executions array required
      each item: object

      • query string required
      • search_type string or null required
      • chunks_retrieved_count integer or null required
      • search_duration_ms integer or null required
      • average_relevance_score number or null required
      • error_message string or null required
• ai_usage object or null required
  • total_calls integer required
  • total_input_tokens integer required
  • total_output_tokens integer required
  • total_tokens integer required
  • total_cost number required
  • by_model object required
• has_more boolean required

Record a note on a lead, signed by the token's owner. Notes are added, never edited, and are visible to the team only.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• id integer required
• body string required

• lead object required
  • id integer required
  • name string or null required
  • email string or null required
  • phone string or null required
  • status string required one of new contacted qualified won lost
  • channel string or null required
  • message string or null required
  • details object required
  • notes array required

    The team's notes, oldest first.

    each item: object

    • body string required
    • author_name string or null required
    • created_at string required
  • conversation_id integer or null required
  • contact_id integer or null required
  • marketing_team_id integer or null required
  • assignee_id integer or null required

    The assigned workspace membership.

  • assignee_name string or null required
  • archived boolean required
  • test_mode boolean required

    Captured by a test run of a flow: kept off the board, nobody is assigned or notified, and it does not count toward the plan.

  • tags array required
    each item: string
  • category object or null required
    • id integer required
    • name string required
  • created_at string required
  • updated_at string required

Add a lead. Like a flow's Save Lead step, it updates the open lead with the same email or phone instead of adding a second one. A new lead goes to the marketing team and member given, or the team's next member in turn, and notifies the team.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• name string optional
• email string optional
• phone string optional
• message string optional
• marketing_team_id integer or null optional
• assignee_id integer or null optional

  A workspace membership id, or null to unassign.

• category_id integer or null optional

  The lead's category (leads.list_categories), or null for none.

• tags array optional

  Free labels. On update this replaces the lead's tags; on create a returning visitor's lead gains them. New names join the workspace's tags.

  each item: string
• details object optional

• lead object required
  • id integer required
  • name string or null required
  • email string or null required
  • phone string or null required
  • status string required one of new contacted qualified won lost
  • channel string or null required
  • message string or null required
  • details object required
  • notes array required

    The team's notes, oldest first.

    each item: object

    • body string required
    • author_name string or null required
    • created_at string required
  • conversation_id integer or null required
  • contact_id integer or null required
  • marketing_team_id integer or null required
  • assignee_id integer or null required

    The assigned workspace membership.

  • assignee_name string or null required
  • archived boolean required
  • test_mode boolean required

    Captured by a test run of a flow: kept off the board, nobody is assigned or notified, and it does not count toward the plan.

  • tags array required
    each item: string
  • category object or null required
    • id integer required
    • name string required
  • created_at string required
  • updated_at string required
• created boolean required

Delete a lead category. It comes off the leads filed under it; the leads stay. Workspace owners and admins only.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• id integer required

• id integer required
• deleted boolean required

Fetch one lead, with everything the flow collected and the team's notes.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• id integer required

• lead object required
  • id integer required
  • name string or null required
  • email string or null required
  • phone string or null required
  • status string required one of new contacted qualified won lost
  • channel string or null required
  • message string or null required
  • details object required
  • notes array required

    The team's notes, oldest first.

    each item: object

    • body string required
    • author_name string or null required
    • created_at string required
  • conversation_id integer or null required
  • contact_id integer or null required
  • marketing_team_id integer or null required
  • assignee_id integer or null required

    The assigned workspace membership.

  • assignee_name string or null required
  • archived boolean required
  • test_mode boolean required

    Captured by a test run of a flow: kept off the board, nobody is assigned or notified, and it does not count toward the plan.

  • tags array required
    each item: string
  • category object or null required
    • id integer required
    • name string required
  • created_at string required
  • updated_at string required

List the workspace's leads, newest first, optionally filtered by status, marketing team, assignee, or a search term matched against name, email and phone. Archived leads are left out unless archived is true, which lists only them. Leads captured by test runs of a flow are left out unless include_test is true.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• status string optional one of new contacted qualified won lost
• marketing_team_id integer optional
• assignee_id integer optional
• search string optional
• archived boolean optional
• include_test boolean optional

  Also list leads captured by test runs of a flow (flow.run), marked test_mode.

• category_id integer optional

  Only leads in this category.

• tag string optional

  Only leads carrying this tag (leads.list_tags), matched ignoring case.

• limit integer optional
• offset integer optional

• leads array required
  each item: object

  • id integer required
  • name string or null required
  • email string or null required
  • phone string or null required
  • status string required one of new contacted qualified won lost
  • channel string or null required
  • message string or null required
  • details object required
  • notes array required

    The team's notes, oldest first.

    each item: object

    • body string required
    • author_name string or null required
    • created_at string required
  • conversation_id integer or null required
  • contact_id integer or null required
  • marketing_team_id integer or null required
  • assignee_id integer or null required

    The assigned workspace membership.

  • assignee_name string or null required
  • archived boolean required
  • test_mode boolean required

    Captured by a test run of a flow: kept off the board, nobody is assigned or notified, and it does not count toward the plan.

  • tags array required
    each item: string
  • category object or null required
    • id integer required
    • name string required
  • created_at string required
  • updated_at string required
• has_more boolean required

The workspace's lead categories, for setting a lead's category_id or filtering leads.list by category_id.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• categories array required
  each item: object

  • id integer required
  • name string required

The workspace's lead tags with how many leads carry each, for tagging leads or filtering leads.list by tag.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• tags array required
  each item: object

  • name string required
  • lead_count integer required

Add a lead category, or rename one when id is given. Workspace owners and admins only.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• id integer optional
• name string required

• category object required
  • id integer required
  • name string required

Give a workspace member a marketing agent seat, or switch it on or off. A new or re-enabled seat draws on the plan's agent seats, which support and marketing share and which are billed beyond the plan's included number; someone holding both takes one. Switching a marketing seat off keeps the leads they hold with them until reassigned.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• membership_id integer required

  The member's membership id (workforce.list_teams people).

• active boolean required

• marketing_agent object required
  • id integer required
  • membership_id integer or null required
  • name string required
  • email string required
  • active boolean required

Move a lead to another status, set its category or tags, route it to a marketing team or a member, correct its contact details, or archive or restore it. Only the fields given are changed. Leads are archived, never deleted.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• id integer required
• name string optional
• email string optional
• phone string optional
• message string optional
• status string optional one of new contacted qualified won lost
• marketing_team_id integer or null optional
• assignee_id integer or null optional

  A workspace membership id, or null to unassign.

• archived boolean optional

  True puts the lead away in the archive, false restores it. Leads are archived, never deleted.

• category_id integer or null optional

  The lead's category (leads.list_categories), or null for none.

• tags array optional

  Free labels. On update this replaces the lead's tags; on create a returning visitor's lead gains them. New names join the workspace's tags.

  each item: string

• lead object required
  • id integer required
  • name string or null required
  • email string or null required
  • phone string or null required
  • status string required one of new contacted qualified won lost
  • channel string or null required
  • message string or null required
  • details object required
  • notes array required

    The team's notes, oldest first.

    each item: object

    • body string required
    • author_name string or null required
    • created_at string required
  • conversation_id integer or null required
  • contact_id integer or null required
  • marketing_team_id integer or null required
  • assignee_id integer or null required

    The assigned workspace membership.

  • assignee_name string or null required
  • archived boolean required
  • test_mode boolean required

    Captured by a test run of a flow: kept off the board, nobody is assigned or notified, and it does not count toward the plan.

  • tags array required
    each item: string
  • category object or null required
    • id integer required
    • name string required
  • created_at string required
  • updated_at string required

Close a conversation as you, with how it ended (disposition_id), why it missed a target (breach_reason_id) and a note, as its team asks: with dispositions required, one must be given when the team has any, and a breach reason too when it missed a target and the workspace keeps reasons. Needs a support agent seat.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer required
• disposition_id integer or null optional
• breach_reason_id integer or null optional
• note string or null optional

• close object required
  • id integer required
  • conversation_id integer required
  • agent_id integer or null required
  • support_team_id integer or null required
  • closed_by string required one of agent automatic intercom
  • disposition_id integer or null required
  • disposition string or null required
  • breach_reason_id integer or null required
  • breach_reason string or null required
  • note string or null required
  • closed_at string required
  • wrap_up_ends_at string or null required

    ISO 8601 time

  • wrap_up_ended_at string or null required

    ISO 8601 time

Turn down a conversation handed to you, with an optional reason. It goes to the next agent who can take it, keeping its place in line, and is never handed back to you.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer required
• reason string or null optional

• decline object required
  • id integer required
  • conversation_id integer required
  • agent_id integer required
  • support_team_id integer or null required
  • reason string or null required
  • created_at string required
• conversation object required
  • id integer required
  • display_name string required
  • platform string required
  • support_team_id integer or null required
  • queued_at string or null required

    ISO 8601 time

  • priority string required one of low normal high urgent
  • status string required
  • assigned_agent_id integer or null required
  • sla array required
    each item: object

    • kind string required
    • state string required one of ok warning breached
    • due_at string or null required

      ISO 8601 time

    • target_seconds integer required
    • elapsed_seconds integer required
    • paused boolean required

Remove a disposition or breach reason from the workspace's list. Closes already recorded keep their history. Owners and admins.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• list string required one of dispositions breach_reasons
• id integer required

• id integer required
• deleted boolean required

Finish your wrap-up on a conversation you closed, freeing the slot it was holding for the next waiting conversation.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer required

• close object required
  • id integer required
  • conversation_id integer required
  • agent_id integer or null required
  • support_team_id integer or null required
  • closed_by string required one of agent automatic intercom
  • disposition_id integer or null required
  • disposition string or null required
  • breach_reason_id integer or null required
  • breach_reason string or null required
  • note string or null required
  • closed_at string required
  • wrap_up_ends_at string or null required

    ISO 8601 time

  • wrap_up_ended_at string or null required

    ISO 8601 time

The service targets of a team that works on the inbox, or null when it has none.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• support_team_id integer required

• sla_policy object or null required
  • support_team_id integer required
  • counting string required one of business_hours around_the_clock
  • targets object required

    Minutes per priority (urgent, high, normal, low) and target (first_response, next_response, resolution); null is not measured.

    • urgent object optional
      • first_response integer or null optional
      • next_response integer or null optional
      • resolution integer or null optional
    • high object optional
      • first_response integer or null optional
      • next_response integer or null optional
      • resolution integer or null optional
    • normal object optional
      • first_response integer or null optional
      • next_response integer or null optional
      • resolution integer or null optional
    • low object optional
      • first_response integer or null optional
      • next_response integer or null optional
      • resolution integer or null optional
  • breach_bumps_priority boolean required
  • breach_overflows boolean required

How a team that works on the inbox works its queue: how conversations reach its members, how long they may wait, what happens outside its hours, how closing goes, and its conversation limits. inbox.save_team_settings explains each setting.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• support_team_id integer required

  A team that works on the inbox (workforce.list_teams).

• team_settings object required
  • support_team_id integer required
  • assignment_mode string required one of manual push round_robin
  • assigned_only boolean required
  • wait_limit_minutes integer or null required
  • overflow_team_id integer or null required
  • escalation_bumps_priority boolean required
  • after_hours string required one of hold bot
  • after_hours_held_message string or null required
  • after_hours_bot_message string or null required
  • wrap_up_seconds integer or null required
  • disposition_mode string required one of off optional required
  • disposition_ids array required

    Empty offers all of the workspace's dispositions.

    each item: integer
  • concurrency_limit integer or null required

    Open conversations each member takes from this team at once; null leaves each agent's own.

  • member_concurrency_limits array required

    Members' own limits for this team, by membership id.

    each item: object

    • membership_id integer required
    • concurrency_limit integer or null required

Every active support agent with the status they picked, what they show now (offline when disconnected, out_of_office during time off), their limit on open conversations at once, how many they hold, and any per-team limits.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• agents array required
  each item: object

  • id integer required
  • name string required
  • status string required one of available busy away offline

    What the agent picked.

  • presence string required one of available busy away offline out_of_office

    What the agent shows: their status while connected, offline when not, out_of_office during time off.

  • presence_label string required
  • online boolean required
  • concurrency_limit integer required
  • active_conversation_count integer required
  • team_limits array required
    each item: object

    • support_team_id integer required
    • concurrency_limit integer or null required

Live conversations, among those you can see, with a service clock past 75% of its target or already beyond it, most pressing first.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• support_team_id integer optional
• limit integer optional
• offset integer optional

• conversations array required
  each item: object

  • id integer required
  • display_name string required
  • platform string required
  • support_team_id integer or null required
  • queued_at string or null required

    ISO 8601 time

  • priority string required one of low normal high urgent
  • status string required
  • assigned_agent_id integer or null required
  • sla array required
    each item: object

    • kind string required
    • state string required one of ok warning breached
    • due_at string or null required

      ISO 8601 time

    • target_seconds integer required
    • elapsed_seconds integer required
    • paused boolean required
• has_more boolean required

Conversation closes, newest first: who or what closed it, its disposition, breach reason and note, and its wrap-up. A conversation closed more than once has a row per close; the latest is the one that counts. Filter by conversation, agent, team, disposition or a start time.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer optional
• agent_id integer optional
• support_team_id integer optional
• disposition_id integer optional
• since string optional

  ISO 8601

• limit integer optional
• offset integer optional

• closes array required
  each item: object

  • id integer required
  • conversation_id integer required
  • agent_id integer or null required
  • support_team_id integer or null required
  • closed_by string required one of agent automatic intercom
  • disposition_id integer or null required
  • disposition string or null required
  • breach_reason_id integer or null required
  • breach_reason string or null required
  • note string or null required
  • closed_at string required
  • wrap_up_ends_at string or null required

    ISO 8601 time

  • wrap_up_ended_at string or null required

    ISO 8601 time

• has_more boolean required

Conversations agents turned down, newest first, with the reason given. Filter by conversation, agent, team or a start time.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer optional
• agent_id integer optional
• support_team_id integer optional
• since string optional

  ISO 8601

• limit integer optional
• offset integer optional

• declines array required
  each item: object

  • id integer required
  • conversation_id integer required
  • agent_id integer required
  • support_team_id integer or null required
  • reason string or null required
  • created_at string required
• has_more boolean required

The workspace's dispositions (how a conversation ended) and breach reasons (why it missed a target), for closing conversations and setting team dispositions.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• dispositions array required
  each item: object

  • id integer required
  • name string required
• breach_reasons array required
  each item: object

  • id integer required
  • name string required

Escalation steps that fired, newest first: wait_alert (supervisors alerted at the wait limit), wait_overflow (moved to the overflow team at twice the limit), and the service target steps. Risk flag alerts are not escalation steps and are not listed. Filter by conversation, team, kind or a start time.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer optional
• support_team_id integer optional
• kind string optional
• since string optional

  ISO 8601

• limit integer optional
• offset integer optional

• escalations array required
  each item: object

  • id integer required
  • conversation_id integer required
  • support_team_id integer or null required
  • kind string required
  • fired_at string required
• has_more boolean required

Conversations waiting in support team queues for an agent, in the order they will be handed out, limited to the queues you can see. Optionally one team's.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• support_team_id integer optional
• limit integer optional
• offset integer optional

• conversations array required
  each item: object

  • id integer required
  • display_name string required
  • platform string required
  • support_team_id integer or null required
  • queued_at string or null required

    ISO 8601 time

  • priority string required one of low normal high urgent
  • status string required
  • assigned_agent_id integer or null required
  • sla array required
    each item: object

    • kind string required
    • state string required one of ok warning breached
    • due_at string or null required

      ISO 8601 time

    • target_seconds integer required
    • elapsed_seconds integer required
    • paused boolean required
• has_more boolean required

Service targets conversations missed, newest first: which target, at what priority and target length, in which team, and when it ran out. Filter by conversation, team, kind or a start time.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer optional
• support_team_id integer optional
• kind string optional one of first_response next_response resolution
• since string optional

  ISO 8601

• limit integer optional
• offset integer optional

• breaches array required
  each item: object

  • id integer required
  • conversation_id integer required
  • support_team_id integer or null required
  • kind string required
  • priority string required
  • target_seconds integer required
  • breached_at string required
• has_more boolean required

Add a disposition or a breach reason to the workspace's list, or rename one when id is given. list is dispositions or breach_reasons. Owners and admins.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• list string required one of dispositions breach_reasons
• id integer optional
• name string required

• item object required
  • id integer required
  • name string required

Set the service targets of a team that works on the inbox: for each priority, minutes allowed for the first response, each next response and the resolution (null is not measured). counting is business_hours (the team's schedule and holidays) or around_the_clock. breach_bumps_priority and breach_overflows (to the team's overflow team) act when a target is missed. targets replaces the whole set; other fields left out are kept.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• support_team_id integer required
• counting string optional one of business_hours around_the_clock
• targets object optional

  Minutes per priority (urgent, high, normal, low) and target (first_response, next_response, resolution); null is not measured.

  • urgent object optional
    • first_response integer or null optional
    • next_response integer or null optional
    • resolution integer or null optional
  • high object optional
    • first_response integer or null optional
    • next_response integer or null optional
    • resolution integer or null optional
  • normal object optional
    • first_response integer or null optional
    • next_response integer or null optional
    • resolution integer or null optional
  • low object optional
    • first_response integer or null optional
    • next_response integer or null optional
    • resolution integer or null optional
• breach_bumps_priority boolean optional
• breach_overflows boolean optional

• sla_policy object required
  • support_team_id integer required
  • counting string required one of business_hours around_the_clock
  • targets object required

    Minutes per priority (urgent, high, normal, low) and target (first_response, next_response, resolution); null is not measured.

    • urgent object optional
      • first_response integer or null optional
      • next_response integer or null optional
      • resolution integer or null optional
    • high object optional
      • first_response integer or null optional
      • next_response integer or null optional
      • resolution integer or null optional
    • normal object optional
      • first_response integer or null optional
      • next_response integer or null optional
      • resolution integer or null optional
    • low object optional
      • first_response integer or null optional
      • next_response integer or null optional
      • resolution integer or null optional
  • breach_bumps_priority boolean required
  • breach_overflows boolean required

Change how a team that works on the inbox works its queue (switch a team onto the inbox with workforce.save_team works_on). assignment_mode push (default) and round_robin hand waiting conversations to a member with a support seat who is available and under their limit: push picks whoever holds fewest, round_robin goes strictly in turn. With manual nothing is handed out and members claim from the queue. assigned_only stops members claiming from the queue, and needs push or round_robin. wait_limit_minutes counts business time; at the limit the team's supervisors are alerted, at twice it the conversation moves to overflow_team_id (another inbox team), and escalation_bumps_priority raises priority at each step. after_hours is hold (handed over while closed, waiting in the queue until open) or bot (the bot answers instead of handing off while closed and tags the conversation "Asked for a person after hours"); a Universal Desk workspace always holds. after_hours_held_message is sent in place of the handoff message when a visitor is handed to the team while it is closed, after_hours_bot_message instead of a handoff when after_hours is bot; null or empty uses the default, and {{opening_time}}, {{closing_time}} and {{team_name}} are filled in, with times naming the team's time zone. disposition_mode (off, optional, required) is what the close sheet asks, disposition_ids the dispositions it offers (empty is all), wrap_up_seconds how long a closing agent keeps the slot. concurrency_limit is how many of the team's conversations each member takes at once (1 to 100, null leaves each agent's own); member_concurrency_limits sets a member's own limit for this team by membership id, null clearing it, and leaves members not named as they are. Only fields given are changed.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• support_team_id integer required

  A team that works on the inbox (workforce.list_teams).

• assignment_mode string optional one of manual push round_robin
• assigned_only boolean optional
• wait_limit_minutes integer or null optional
• overflow_team_id integer or null optional
• escalation_bumps_priority boolean optional
• after_hours string optional one of hold bot
• after_hours_held_message string or null optional
• after_hours_bot_message string or null optional
• wrap_up_seconds integer or null optional
• disposition_mode string optional one of off optional required
• disposition_ids array optional

  Empty offers all of the workspace's dispositions.

  each item: integer
• concurrency_limit integer or null optional

  Open conversations each member takes from this team at once; null leaves each agent's own.

• member_concurrency_limits array optional

  Members' own limits for this team, by membership id.

  each item: object

  • membership_id integer required
  • concurrency_limit integer or null required

• team_settings object required
  • support_team_id integer required
  • assignment_mode string required one of manual push round_robin
  • assigned_only boolean required
  • wait_limit_minutes integer or null required
  • overflow_team_id integer or null required
  • escalation_bumps_priority boolean required
  • after_hours string required one of hold bot
  • after_hours_held_message string or null required
  • after_hours_bot_message string or null required
  • wrap_up_seconds integer or null required
  • disposition_mode string required one of off optional required
  • disposition_ids array required

    Empty offers all of the workspace's dispositions.

    each item: integer
  • concurrency_limit integer or null required

    Open conversations each member takes from this team at once; null leaves each agent's own.

  • member_concurrency_limits array required

    Members' own limits for this team, by membership id.

    each item: object

    • membership_id integer required
    • concurrency_limit integer or null required

Set how many open conversations a support agent is given at once (1 to 100). With support_team_id, set their own limit for work from that team only; null there clears it back to the team's limit, or the agent's own when the team sets none.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• agent_id integer required
• concurrency_limit integer or null required
• support_team_id integer optional

  An inbox team the agent is on (workforce.list_teams).

• agent object required
  • id integer required
  • name string required
  • status string required one of available busy away offline

    What the agent picked.

  • presence string required one of available busy away offline out_of_office

    What the agent shows: their status while connected, offline when not, out_of_office during time off.

  • presence_label string required
  • online boolean required
  • concurrency_limit integer required
  • active_conversation_count integer required
  • team_limits array required
    each item: object

    • support_team_id integer required
    • concurrency_limit integer or null required

Mark an inbox contact VIP, or not. A VIP's conversations are high priority or above, including the ones open now. Owners and admins only.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• contact_id integer required
• vip boolean required

• id integer required
• vip boolean required

Give or change how a closed conversation ended, on its latest close, with an optional breach reason and note. Anyone seated adds one to a close without; once given, only the closer and the team's supervisors change it.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer required
• disposition_id integer or null optional
• breach_reason_id integer or null optional
• note string or null optional

• close object required
  • id integer required
  • conversation_id integer required
  • agent_id integer or null required
  • support_team_id integer or null required
  • closed_by string required one of agent automatic intercom
  • disposition_id integer or null required
  • disposition string or null required
  • breach_reason_id integer or null required
  • breach_reason string or null required
  • note string or null required
  • closed_at string required
  • wrap_up_ends_at string or null required

    ISO 8601 time

  • wrap_up_ended_at string or null required

    ISO 8601 time

Set how soon a person should pick a conversation up: low, normal, high or urgent. Waiting conversations are handed out highest priority first, then longest waiting. Owners and admins only.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer required
• priority string required one of low normal high urgent

• conversation object required
  • id integer required
  • display_name string required
  • platform string required
  • support_team_id integer or null required
  • queued_at string or null required

    ISO 8601 time

  • priority string required one of low normal high urgent
  • status string required
  • assigned_agent_id integer or null required
  • sla array required
    each item: object

    • kind string required
    • state string required one of ok warning breached
    • due_at string or null required

      ISO 8601 time

    • target_seconds integer required
    • elapsed_seconds integer required
    • paused boolean required

Set your own inbox status: available, busy, away or offline. Only your own seat; nobody sets another agent's status. Busy is never set automatically.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• status string required one of available busy away offline

• agent object required
  • id integer required
  • name string required
  • status string required one of available busy away offline

    What the agent picked.

  • presence string required one of available busy away offline out_of_office

    What the agent shows: their status while connected, offline when not, out_of_office during time off.

  • presence_label string required
  • online boolean required
  • concurrency_limit integer required
  • active_conversation_count integer required
  • team_limits array required
    each item: object

    • support_team_id integer required
    • concurrency_limit integer or null required

Give a workspace member a support agent seat, or switch it on or off. A new or re-enabled seat draws on the plan's agent seats, which support and marketing share and which are billed beyond the plan's included number; someone holding both takes one. Switching a support seat off returns their open conversations to the unassigned queue.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• membership_id integer required

  The member's membership id (workforce.list_teams people).

• active boolean required

• support_agent object required
  • id integer required
  • membership_id integer or null required
  • name string required
  • email string required
  • active boolean required

A support report over a date range, sliced by team, agent, channel, priority, flow or deployment: volumes, queue_time (waiting for the first agent), handling (assignment to close, plus wrap-up), sla (share of targets met), breaches (with breach reasons), dispositions, declines, availability (hours per status; out of office is left out of availability), satisfaction, sentiment (customer mood on a five-point scale before close, from a handoff or a flow step, and at close, each conversation counted once on each side, and how many conversations improved or got worse; by agent only close readings), issues (conversations per issue tag read at any reading, with the latest mood), or risks (conversations per risk flag raised at any reading, with the latest emotion). Times are minutes unless the column says hours. Owners and admins see the whole workspace; a team supervisor their own teams.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• report string required one of volumes queue_time handling sla breaches dispositions declines availability satisfaction sentiment issues risks
• slice string optional one of team agent channel priority flow deployment
• from string optional

  YYYY-MM-DD; defaults to 30 days ago.

• to string optional

  YYYY-MM-DD; defaults to today.

• title string required
• columns array required
  each item: string
• rows array required
  each item: array

  each item: string or number or null

Mark an open conversation as waiting on the customer: its resolution clock pauses, and it goes back to open when the customer writes. Needs a support agent seat.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• conversation_id integer required

• conversation object required
  • id integer required
  • display_name string required
  • platform string required
  • support_team_id integer or null required
  • queued_at string or null required

    ISO 8601 time

  • priority string required one of low normal high urgent
  • status string required
  • assigned_agent_id integer or null required
  • sla array required
    each item: object

    • kind string required
    • state string required one of ok warning breached
    • due_at string or null required

      ISO 8601 time

    • target_seconds integer required
    • elapsed_seconds integer required
    • paused boolean required

Delete a team, with its settings in every feature. Its conversations leave the team queue and become visible to every agent, its leads keep their assignees but no longer have a team, and deployments and flows that defaulted to it fall back.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• id integer required

• id integer required
• deleted boolean required

End time off now; the person comes back as offline. Time off that has not started is removed instead (ended: false).

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• id integer required

• id integer required
• ended boolean required

Time off that is current or still to come: yours, your teams' members' for a supervisor, or everyone's for an owner, manager or admin. While someone is out they are handed no conversations or leads and get no notifications.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• absences array required
  each item: object

  • id integer required
  • membership_id integer required
  • name string required
  • starts_at string required
  • ends_at string or null required

    ISO 8601 time; null has no return date yet.

  • note string or null required
  • hand_back_conversations boolean required
  • current boolean required

The workspace's teams and people. Each team has its hours, holidays, the features it works on (works_on), and its members by membership id with whether they supervise and which seats they hold; a team on the inbox also has a summary of its inbox rules. people lists every member of the workspace with their seats, switched-off seats included, and features the keys a team can work on here. works_on narrows the teams to those working on one feature. Use the ids with the other workforce.* tools, inbox.set_support_agent and leads.set_marketing_agent. Emails and roles are included for an owner, manager or admin calling with read:workforce.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• works_on string optional

  A feature key, such as inbox or leads.

• teams array required
  each item: object

  • id integer required
  • name string required
  • description string or null required
  • time_zone string required
  • business_hours object or null required
    • mon array optional
      each item: array

      each item: string
    • tue array optional
      each item: array

      each item: string
    • wed array optional
      each item: array

      each item: string
    • thu array optional
      each item: array

      each item: string
    • fri array optional
      each item: array

      each item: string
    • sat array optional
      each item: array

      each item: string
    • sun array optional
      each item: array

      each item: string
  • business_hours_text string required

    The schedule as lines like Mon-Fri 09:00-17:00; empty is always open.

  • holidays array required
    each item: object

    • date string required

      YYYY-MM-DD

    • name string or null required
  • works_on array required
    each item: string
  • members array required
    each item: object

    • membership_id integer required
    • name string required
    • email string optional
    • supervisor boolean required
    • seats array required

      The active seats the person holds.

      each item: string
  • inbox object or null required
    • assignment_mode string required one of manual push round_robin
    • assigned_only boolean required
    • after_hours string required one of hold bot
    • wait_limit_minutes integer or null required
    • overflow_team_id integer or null required
    • concurrency_limit integer or null required
    • disposition_mode string required one of off optional required
    • has_sla_policy boolean required
• people array required
  each item: object

  • membership_id integer required
  • name string required
  • email string optional
  • role string optional
  • active boolean required
  • support_seat object or null required
    • id integer required
    • active boolean required
  • marketing_seat object or null required
    • id integer required
    • active boolean required
• features array required
  each item: object

  • key string required
  • label string required

Set time off, or change it when id is given. Without membership_id it is your own; an owner, manager or admin may name anyone's, and a team supervisor their team's members' (membership ids from workforce.list_teams people). hand_back_conversations (default true) returns the person's open conversations to their team's queue when it starts. ends_at null means no return date yet. Only fields given are changed.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• id integer optional
• membership_id integer optional
• starts_at string optional

  ISO 8601; defaults to now for new time off.

• ends_at string or null optional

  ISO 8601

• note string or null optional
• hand_back_conversations boolean optional

• absence object required
  • id integer required
  • membership_id integer required
  • name string required
  • starts_at string required
  • ends_at string or null required

    ISO 8601 time; null has no return date yet.

  • note string or null required
  • hand_back_conversations boolean required
  • current boolean required

Create a team, or change one when id is given. A team is a group of people with the hours it works, and it does the work of the features it works on (works_on, keys from workforce.list_teams features): inbox hands it conversations, leads hands it leads in turn, and so on, each to the members holding that feature's seat. member_ids replaces the members (membership ids from workforce.list_teams people); supervisor_ids names which of them lead the team in every feature it works on, and must all be members. business_hours is a weekly schedule in time_zone (null is always open); holidays replaces the closed days. works_on replaces the features; switching one off keeps its settings for when it is switched back on. inbox.save_team_settings sets the inbox rules of a team on the inbox. Only fields given are changed. Creating a team and changing member_ids or supervisor_ids is for an owner or manager; an admin changes the rest.

• workspace string required

  Subdomain of the workspace to operate on. workspaces.list reports the ones this token can reach.

• id integer optional
• name string optional
• description string or null optional
• time_zone string optional

  A time zone, such as Africa/Lagos, Europe/London or UTC. A Rails zone name such as London is stored as the zone it stands for.

• business_hours object or null optional
  • mon array optional
    each item: array

    each item: string
  • tue array optional
    each item: array

    each item: string
  • wed array optional
    each item: array

    each item: string
  • thu array optional
    each item: array

    each item: string
  • fri array optional
    each item: array

    each item: string
  • sat array optional
    each item: array

    each item: string
  • sun array optional
    each item: array

    each item: string
• holidays array optional
  each item: object

  • date string required

    YYYY-MM-DD

  • name string or null required
• member_ids array optional
  each item: integer
• supervisor_ids array optional
  each item: integer
• works_on array optional
  each item: string