Conversations

Manage Inbox items including direct messages, post comments, mentions, and replies from connected profiles. Use these endpoints to list, view, update, and act on any conversation in your Oktopost Inbox.

List Conversations

Retrieve all inbox items matching the given filters. By default returns all item types (direct messages, post comments, mentions, and replies).

Parameters

Parameter	Type	Required	Description
type	String	No	Comma-separated list of item types. Accepted values: `Conversation`, `Post`, `Mention`, `Reply`. Defaults to all types.
status	String	No	Comma-separated list of statuses. Accepted values: `open`, `closed`
network	String	No	Comma-separated list of social networks. Accepted values: `Facebook`, `Twitter`, `LinkedIn`, `YouTube`, `Instagram`
assignee_id	String	No	Comma-separated list of user IDs to filter by assignee.
tag	String	No	Comma-separated list of conversation tag names to filter by.
q	String	No	Free-text search term.
_count	Integer	No	Maximum number of results to return.

Example Request

curl -i https://api.oktopost.com/v2/conversation?status=open&type=Post,Mention

Example Result

{
	"Result": true,
	"Conversations": {
		"Total": 42,
		"Items": [
			{
				"Id": "eit000000000001",
				"Created": "2025-03-10 14:22:00",
				"Modified": "2025-03-12 09:15:30",
				"Status": "open",
				"Network": "Facebook",
				"ItemType": "Post",
				"AssigneeId": "00A000000000001",
				"ProfileName": "Acme Inc"
			},
			...
		]
	}
}

Get Conversation

Retrieve a single inbox item by ID. The response includes the item's assigned tags.

Example Request

curl -i https://api.oktopost.com/v2/conversation/eit000000000001

Example Result

{
	"Result": true,
	"Conversation": {
		"Id": "eit000000000001",
		"Created": "2025-03-10 14:22:00",
		"Modified": "2025-03-12 09:15:30",
		"Status": "open",
		"Network": "LinkedIn",
		"ItemType": "conversation",
		"AssigneeId": "00A000000000001",
		"ProfileName": "Acme Inc",
		"Tags": [
			{
				"Id": "etg000000000001",
				"Name": "Support"
			}
		]
	}
}

Update Conversation Status

Open or close an inbox item.

Parameters

Parameter	Type	Required	Description
status	String	Yes	The new status. Accepted values: `open`, `closed`

Example Request

curl -i https://api.oktopost.com/v2/conversation/eit000000000001 -X POST \
	-d status="closed"

Example Result

{
	"Result": true
}

Get Timeline

Retrieve the timeline of an inbox item, including messages, comments, notes, shares, and likes. Supports cursor-based pagination.

Parameters

Parameter	Type	Required	Description
last_loaded_id	String	No	The ID of the last loaded timeline entry. Used for cursor-based pagination to load older entries.

Example Request

curl -i https://api.oktopost.com/v2/conversation/eit000000000001/timeline

Example Result

{
	"Result": true,
	"Timeline": [
		{
			"Id": "eat000000000001",
			"Type": "note",
			"Created": "2025-03-12 09:15:30",
			"Content": "Following up with the customer.",
			"CreatedBy": "00A000000000001"
		},
		{
			"Id": "eat000000000002",
			"Type": "share",
			"Created": "2025-03-11 16:45:00",
			"Content": "Thanks for reaching out!"
		}
	]
}

Assign Conversation

Assign an inbox item to a user. Optionally include a note that will also be added to the item's timeline.

Parameters

Parameter	Type	Required	Description
assignee_id	String	Yes	The user ID to assign the conversation to.
note	String	No	An optional note (max 10,000 characters) to attach with the assignment.

Example Request

curl -i https://api.oktopost.com/v2/conversation/eit000000000001/assign -X POST \
	-d assignee_id="00A000000000002" \
	-d note="Please handle this VIP customer"

Example Result

{
	"Result": true,
	"Assignment": {
		"ItemId": "eit000000000001",
		"AssigneeId": "00A000000000002"
	}
}

Add Note

Add an internal note to an inbox item's timeline.

Parameters

Parameter	Type	Required	Description
note	String	Yes	The note text (max 10,000 characters).

Example Request

curl -i https://api.oktopost.com/v2/conversation/eit000000000001/note -X POST \
	-d note="Escalated to engineering team"

Example Result

{
	"Result": true,
	"Note": {
		"Id": "eat000000000003",
		"Type": "note",
		"Created": "2025-03-12 10:30:00",
		"Content": "Escalated to engineering team",
		"CreatedBy": "00A000000000001"
	}
}

Update Tags

Replace the tags assigned to an inbox item. Pass the full list of tag names; any previously assigned tags not in the list will be removed.

Parameters

Parameter	Type	Required	Description
tags	Array	Yes	Array of conversation tag names to assign.

Example Request

curl -i https://api.oktopost.com/v2/conversation/eit000000000001/tag -X POST \
	-d tags[]="Support" \
	-d tags[]="VIP"

Example Result

{
	"Result": true,
	"Tags": [
		{
			"Id": "etg000000000001",
			"Name": "Support"
		},
		{
			"Id": "etg000000000002",
			"Name": "VIP"
		}
	]
}

Reply

Send a reply or comment on an inbox item. For direct messages (Conversation type), this sends a DM reply. For public items (Post, Mention, Reply types), this adds a comment. The item must be in open status.

Parameters

Parameter	Type	Required	Description
message	String	Yes	The reply text (max 10,000 characters).
credential_id	String	No	The credential ID to send the reply from. If omitted, the item's default credential is used.
parent_comment_id	String	No	For public items: the ID of a parent comment to reply to (threading). Supported on Facebook, LinkedIn, Instagram, TikTok, and YouTube. Ignored for direct messages.
media	Array	No	Array of media objects to attach. Supported on Facebook, X (Twitter), LinkedIn, and TikTok. Ignored on networks that don't support media attachments.

Example Request — DM Reply

curl -i https://api.oktopost.com/v2/conversation/eit000000000001/reply -X POST \
	-d message="Thanks for reaching out! We'll look into this right away."

Example Request — Public Comment with Threading

curl -i https://api.oktopost.com/v2/conversation/eit000000000002/reply -X POST \
	-d message="Thanks for the feedback!" \
	-d parent_comment_id="eit000000000003"

Example Result

{
	"Result": true
}

For direct messages (Conversation type), replies are supported on Facebook, X (Twitter), and LinkedIn. For public items (Post, Mention, Reply types), comments are supported on Facebook, X (Twitter), LinkedIn, Instagram, TikTok, and YouTube. Attempting to reply on an unsupported network will return a 400 error.

Create Salesforce Case

Create or update a Salesforce case linked to an inbox item. Requires an active Salesforce integration.

Parameters

Parameter	Type	Required	Description
integration_id	String	Yes	The Salesforce case integration ID.
case_owner	String	No	The Salesforce case owner.
contact_id	String	No	The Salesforce contact ID to associate with the case.
case_description	String	No	A description for the Salesforce case (max 10,000 characters).

Example Request

curl -i https://api.oktopost.com/v2/conversation/eit000000000001/create-case -X POST \
	-d integration_id="sfint00000000001" \
	-d case_owner="005000000000001" \
	-d contact_id="003000000000001" \
	-d case_description="Customer reported an issue with login"

Example Result

{
	"Result": true
}

This endpoint requires a Salesforce integration to be enabled. If no integration is active, the request will return a 400 error.

On this page