Conversations: list and search with starting_after paging, read, reply (visible to the customer) or add internal notes, and manage state: assign, snooze, open, close. Everything that acts does so as the admin in intercom.admin.id.

Context Vars

Optional
  • intercom.token
  • intercom.admin.id

Functions

add-note

fn (conversation-id: Str, body: Str): Any
fn (conversation-id: Str, body: Str, opts: Map): Any

POST /conversations/{id}/reply with message_type: note - An internal note teammates see but the customer doesn't.

Example

::intercom::conversations/add-note("215473041", "Customer is on the enterprise plan. Escalate to tier 2.")
Context Vars: intercom.admin.id

assign-conversation

fn (conversation-id: Str, assignee-id: Str): Any
fn (conversation-id: Str, assignee-id: Str, options: Map): Any
fn (conversation-id: Str, assignee-id: Str, options: Map, opts: Map): Any

Assign a conversation to an admin (default) or a team. options: type ("admin" or "team"), body (a note posted with the assignment), skip_reopen (keep a closed conversation closed).

Example

::intercom::conversations/assign-conversation("215473041", "814860", {type: "team", body: "Billing question"})
Context Vars: intercom.admin.id

build-assign-body

fn (admin-id: Str, assignee-id: Str, options: Map): Map

Assignment body: {message_type: "assignment", type, admin_id, assignee_id, body?, skip_reopen?}. type is the assignee kind, "admin" or "team"; admin_id is the admin performing it. assignee_id "0" unassigns. Exposed for testing.

Example

::intercom::conversations/build-assign-body("814860", "5017691", {type: "team"})
// {message_type: "assignment", type: "team", admin_id: "814860", assignee_id: "5017691"}

build-close-body

fn (admin-id: Str, body: Str?): Map

Close body: {message_type: "close", type: "admin", admin_id, body?}. Exposed for testing.

Example

::intercom::conversations/build-close-body("814860", "All set.")  // {message_type: "close", type: "admin", admin_id: "814860", body: "All set."}
::intercom::conversations/build-close-body("814860", null)  // {message_type: "close", type: "admin", admin_id: "814860"}

build-open-body

fn (admin-id: Str): Map

Open body: {message_type: "open", admin_id}. Exposed for testing.

Example

::intercom::conversations/build-open-body("814860")  // {message_type: "open", admin_id: "814860"}

build-reply-body

fn (message-type: Str, admin-id: Str, body: Str, options: Map): Map

Build an admin reply body: message_type ("comment", "note" or "quick_reply"), type: "admin", admin_id and body, plus options (attachment_urls, skip_notifications, created_at). Unset options are omitted. Exposed for testing.

Example

::intercom::conversations/build-reply-body("comment", "814860", "Thanks!", {skip_notifications: true})
// {skip_notifications: true, message_type: "comment", type: "admin", admin_id: "814860", body: "Thanks!"}

build-snooze-body

fn (admin-id: Str, snoozed-until: Int): Map

Snooze body: {message_type: "snoozed", admin_id, snoozed_until} (Unix seconds). Exposed for testing.

Example

::intercom::conversations/build-snooze-body("814860", 1767225600)  // {message_type: "snoozed", admin_id: "814860", snoozed_until: 1767225600}

close-conversation

fn (conversation-id: Str): Any
fn (conversation-id: Str, opts: Map): Any
fn (conversation-id: Str, body: Str): Any
fn (conversation-id: Str, body: Str, opts: Map): Any

Close a conversation, optionally with a closing message to the customer.

Example

::intercom::conversations/close-conversation("215473041")

// With a closing message to the customer
::intercom::conversations/close-conversation("215473041", "Glad that fixed it. Closing this out.")
Context Vars: intercom.admin.id

get-conversation

fn (id: Str): Any
fn (id: Str, options: Map): Any
fn (id: Str, options: Map, opts: Map): Any

GET /conversations/{id} - A conversation with its conversation_parts (messages, notes, assignment and state changes). options: display_as: "plaintext", include_translations.

Example

convo ::intercom::conversations/get-conversation("215473041", {display_as: "plaintext"})
map(convo.conversation_parts.conversation_parts, %.body)

list-conversations

fn (): Any
fn (options: Map): Any
fn (options: Map, opts: Map): Any

GET /conversations - One page of conversations, newest first: {type, conversations, pages, total_count}. options: per_page (default 20, max 150) and starting_after (from ::intercom::api/next-cursor(page)).

Example

page ::intercom::conversations/list-conversations({per_page: 50})
length(page.conversations)

// The next page
more ::intercom::conversations/list-conversations({per_page: 50, starting_after: ::intercom::api/next-cursor(page)})

open-conversation

fn (conversation-id: Str): Any
fn (conversation-id: Str, opts: Map): Any

Reopen a snoozed or closed conversation.

Example

::intercom::conversations/open-conversation("215473041")
Context Vars: intercom.admin.id

reply

fn (conversation-id: Str, body: Str): Any
fn (conversation-id: Str, body: Str, options: Map): Any
fn (conversation-id: Str, body: Str, options: Map, opts: Map): Any

POST /conversations/{id}/reply - Reply to the customer as the configured admin (visible to them). body may be HTML. options: attachment_urls, skip_notifications.

Example

::intercom::conversations/reply("215473041", "Thanks for the report! A fix ships this week.")

// With an attachment, sent quietly
::intercom::conversations/reply("215473041", "Here is the export.", {
  attachment_urls: ["https://example.com/export.csv"],
  skip_notifications: true
})
Context Vars: intercom.admin.id

search-all-conversations

fn (query: Map, limit: Int): Vec
fn (query: Map, limit: Int, opts: Map): Vec

Run search-conversations across pages (150 per page) until limit conversations or the last page. Returns a Vec.

Example

convos ::intercom::conversations/search-all-conversations({field: "open", operator: "=", value: true}, 500)
length(convos)

search-conversations

fn (query: Map): Any
fn (query: Map, options: Map): Any
fn (query: Map, options: Map, opts: Map): Any

POST /conversations/search - One page of results for Intercom's query DSL: a single {field, operator, value} or {operator: "AND"/"OR", value: [...]}. options: per_page (max 150) and starting_after. Returns {conversations, pages, total_count}.

Example

page ::intercom::conversations/search-conversations({
  operator: "AND",
  value: [
    {field: "open", operator: "=", value: true},
    {field: "updated_at", operator: ">", value: 1767225600}
  ]
}, {per_page: 50})
next ::intercom::api/next-cursor(page)

snooze-conversation

fn (conversation-id: Str, snoozed-until: Int): Any
fn (conversation-id: Str, snoozed-until: Int, opts: Map): Any

Snooze a conversation until snoozed-until (Unix seconds); it reopens then.

Example

tomorrow add(::hot::time/epoch-seconds(), 86400)
::intercom::conversations/snooze-conversation("215473041", tomorrow)
Context Vars: intercom.admin.id