Checking authentication...

Conversations

Send and manage private conversations between Podio users

11 tools

Create Conversation

Write

POST /v1/tools/podio/createConversation

Create a new conversation with specified users. Uses v2 endpoint for richer response. Participants should be user IDs (not profile IDs) — call getOrganizationMembers or getContacts first to look up user IDs.

Parameters

Name	Type	Required	Description
`subject`	string	required	Subject/title of the conversation
`text`	string	required	Initial message text for the conversation
`participants`	array	required	Array of user IDs to include in the conversation (excluding the sender)
`file_ids`	array	optional	Optional array of file IDs or URLs to attach to the initial message. URLs (https://...) are auto-uploaded and converted to file IDs.
`embed_url`	string	optional	Optional URL to embed in the message
`embed_id`	number	optional	Optional embed ID (if already created via embed API)

Request

curl -X POST https://api.syncello.io/v1/tools/podio/createConversation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '{
  "subject": "example",
  "text": "example",
  "participants": "..."
}'

Response

{
  "conversation_id": 58203417,
  "subject": "Deal review",
  "excerpt": "Hi — can you review the Northwind Traders proposal?",
  "type": "group",
  "created_by": {
    "user_id": 1122334,
    "name": "Jane Doe",
    "type": "user"
  },
  "created_on": "2026-07-01 16:16:25",
  "last_event_on": "2026-07-01 16:16:25",
  "participants": [
    {
      "user_id": 1122334,
      "profile_id": 4455667,
      "name": "Jane Doe",
      "type": "user"
    },
    {
      "user_id": 1122335,
      "profile_id": 4455668,
      "name": "John Smith",
      "type": "user"
    }
  ],
  "starred": false,
  "unread": false,
  "unread_count": 0
}

Try It

Try it

Create Conversation On Object

Write

POST /v1/tools/podio/createConversationOnObject

Create a conversation on a specific Podio object (like a notification). The conversation is linked to the object. Participants should be user IDs — call getOrganizationMembers or getContacts first to look up user IDs.

Parameters

Name	Type	Required	Description
`ref_type`	string	required	The type of object to link the conversation to (e.g. "item", "task")
`ref_id`	number	required	The ID of the object to link the conversation to
`subject`	string	required	Subject/title of the conversation
`text`	string	required	Initial message text for the conversation
`participants`	array	required	Array of user IDs to include in the conversation (excluding the sender)
`file_ids`	array	optional	Optional array of file IDs or URLs to attach to the initial message. URLs (https://...) are auto-uploaded and converted to file IDs.
`embed_url`	string	optional	Optional URL to embed in the message
`embed_id`	number	optional	Optional embed ID (if already created via embed API)

Request

curl -X POST https://api.syncello.io/v1/tools/podio/createConversationOnObject \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '{
  "ref_type": "example",
  "ref_id": "123",
  "subject": "example",
  "text": "example",
  "participants": "..."
}'

Response

{
  "conversation_id": 58203418,
  "message_id": 169700480,
  "embed_id": null,
  "embed_file_id": null
}

Try It

Try it

Get Conversation

Read Idempotent

POST /v1/tools/podio/getConversation

Get a specific conversation including participants. Only participants in the conversation can view it. Use getConversations or searchConversations to find the conversation_id first.

Parameters

Name	Type	Required	Description
`conversation_id`	number	required	The ID of the conversation to retrieve

Request

curl -X POST https://api.syncello.io/v1/tools/podio/getConversation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '{
  "conversation_id": "123"
}'

Response

{
  "conversation_id": 58203417,
  "subject": "Project kickoff",
  "excerpt": "Thanks — I will send the updated timeline by Friday.",
  "created_by": {
    "user_id": 1122335,
    "name": "John Smith",
    "type": "user"
  },
  "created_on": "2026-06-20 09:30:00",
  "last_event_on": "2026-07-01 16:10:00",
  "link": "https://podio.com/conversations#58203417",
  "messages": [],
  "participants": [
    {
      "user_id": 1122334,
      "profile_id": 4455667,
      "name": "Jane Doe",
      "type": "user"
    },
    {
      "user_id": 1122335,
      "profile_id": 4455668,
      "name": "John Smith",
      "type": "user"
    }
  ],
  "starred": false,
  "unread": false,
  "unread_count": 0,
  "type": "direct"
}

Try It

Try it

Get Conversation Events

Read Idempotent

POST /v1/tools/podio/getConversationEvents

Get the messages and events in a conversation. Returns the actual message content, senders, and timestamps. Use getConversations or searchConversations to find the conversation_id first.

Parameters

Name	Type	Required	Description
`conversation_id`	number	required	The ID of the conversation
`limit`	number	optional	Max events to return (default: 10)
`offset`	number	optional	Pagination offset (default: 0)

Request

curl -X POST https://api.syncello.io/v1/tools/podio/getConversationEvents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '{
  "conversation_id": "123"
}'

Response

[
  {
    "action": "message",
    "created_on": "2026-07-01 16:10:00",
    "created_by": {
      "user_id": 1122335,
      "name": "John Smith",
      "type": "user"
    },
    "created_via": {
      "id": 1,
      "name": "Podio",
      "url": null
    },
    "data": {
      "message_id": 169700490,
      "text": "Thanks — I will send the updated timeline by Friday.",
      "created_on": "2026-07-01 16:10:00"
    }
  }
]

Try It

Try it

Get Conversations

Read Idempotent

POST /v1/tools/podio/getConversations

List all conversations for the authenticated user, ordered by most recent activity. Use limit and offset for pagination.

Parameters

Name	Type	Required	Description
`limit`	number	optional	Max conversations to return (default: 10)
`offset`	number	optional	Pagination offset (default: 0)

Request

curl -X POST https://api.syncello.io/v1/tools/podio/getConversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

[
  {
    "conversation_id": 58203417,
    "subject": "Project kickoff",
    "excerpt": "Thanks — I will send the updated timeline by Friday.",
    "created_by": {
      "user_id": 1122335,
      "name": "John Smith",
      "type": "user"
    },
    "created_on": "2026-06-20 09:30:00",
    "last_event_on": "2026-07-01 16:10:00",
    "participants": [
      {
        "user_id": 1122334,
        "name": "Jane Doe"
      },
      {
        "user_id": 1122335,
        "name": "John Smith"
      }
    ],
    "starred": false,
    "unread": false,
    "unread_count": 0,
    "type": "direct"
  }
]

Try It

Try it

Get Conversations On Object

Read Idempotent

POST /v1/tools/podio/getConversationsOnObject

List all conversations on a specific Podio object (e.g. item, task) that the user is part of. Use ref_type "item" with an item_id, or "task" with a task_id.

Parameters

Name	Type	Required	Description
`ref_type`	string	required	Object type, e.g. "item", "task"
`ref_id`	number	required	Object ID (item_id, task_id, etc.)

Request

curl -X POST https://api.syncello.io/v1/tools/podio/getConversationsOnObject \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '{
  "ref_type": "example",
  "ref_id": "123"
}'

Response

[
  {
    "conversation_id": 58203418,
    "subject": "Question about this deal",
    "excerpt": "Can someone follow up on the contact info?",
    "last_event_on": "2026-07-01 12:00:00",
    "participants": [
      {
        "user_id": 1122334,
        "name": "Jane Doe"
      }
    ]
  }
]

Try It

Try it

Get Direct Conversation

Read Idempotent

POST /v1/tools/podio/getDirectConversation

Get the existing direct (1-on-1) conversation with a specific user. Returns 404 if no direct conversation exists yet. Use getContacts or searchPodio with ref_type "profile" to find user IDs.

Parameters

Name	Type	Required	Description
`user_id`	number	required	The user ID of the other participant

Request

curl -X POST https://api.syncello.io/v1/tools/podio/getDirectConversation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '{
  "user_id": "123"
}'

Response

{
  "conversation_id": 58203417,
  "subject": "Project kickoff",
  "excerpt": "Thanks — I will send the updated timeline by Friday.",
  "created_by": {
    "user_id": 1122335,
    "name": "John Smith",
    "type": "user"
  },
  "created_on": "2026-06-20 09:30:00",
  "last_event_on": "2026-07-01 16:10:00",
  "link": "https://podio.com/conversations#58203417",
  "messages": [],
  "participants": [
    {
      "user_id": 1122334,
      "profile_id": 4455667,
      "name": "Jane Doe",
      "type": "user"
    },
    {
      "user_id": 1122335,
      "profile_id": 4455668,
      "name": "John Smith",
      "type": "user"
    }
  ],
  "starred": false,
  "unread": false,
  "unread_count": 0,
  "type": "direct"
}

Try It

Try it

Search Conversations

Read Idempotent

POST /v1/tools/podio/searchConversations

Search conversations by text. By default searches subjects and message content. Set participants=true to search by participant name or email instead.

Parameters

Name	Type	Required	Description
`text`	string	required	The text to search for
`limit`	number	optional	Max results to return
`offset`	number	optional	Pagination offset
`participants`	boolean	optional	When true, search participant names/emails instead of message content

Request

curl -X POST https://api.syncello.io/v1/tools/podio/searchConversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '{
  "text": "example"
}'

Response

[
  {
    "conversation_id": 58203417,
    "subject": "Project kickoff",
    "excerpt": "Thanks — I will send the updated timeline by Friday.",
    "created_on": "2026-06-20 09:30:00",
    "last_event_on": "2026-07-01 16:10:00",
    "participants": [
      {
        "user_id": 1122334,
        "name": "Jane Doe"
      },
      {
        "user_id": 1122335,
        "name": "John Smith"
      }
    ],
    "unread": false,
    "type": "direct"
  }
]

Try It

Try it

Reply To Conversation

Write

POST /v1/tools/podio/replyToConversation

Reply to an existing conversation. Uses v2 endpoint which returns the conversation event. The authenticated user must be a participant in the conversation.

Parameters

Name	Type	Required	Description
`conversation_id`	number	required	The ID of the conversation to reply to
`text`	string	required	The reply message text
`file_ids`	array	optional	Optional array of file IDs or URLs to attach to the reply. URLs (https://...) are auto-uploaded and converted to file IDs.
`embed_url`	string	optional	Optional URL to embed in the reply
`embed_id`	number	optional	Optional embed ID (if already created via embed API)

Request

curl -X POST https://api.syncello.io/v1/tools/podio/replyToConversation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '{
  "conversation_id": "123",
  "text": "example"
}'

Response

{
  "event_id": 620044556,
  "action": "message",
  "created_on": "2026-07-01 16:23:33",
  "created_by": {
    "user_id": 1122334,
    "name": "Jane Doe",
    "type": "user"
  },
  "created_via": {
    "id": 90001,
    "name": "Syncello",
    "url": null
  },
  "data": {
    "message_id": 169700490,
    "text": "Thanks — I will send the updated timeline by Friday.",
    "embed": null,
    "embed_file": null,
    "files": [],
    "created_on": "2026-07-01 16:23:33"
  }
}

Try It

Try it

Add Conversation Participants

Write

POST /v1/tools/podio/addConversationParticipants

Add new participants to an existing conversation. Uses v2 endpoint. Look up user IDs first via getOrganizationMembers or getContacts.

Parameters

Name	Type	Required	Description
`conversation_id`	number	required	The ID of the conversation to add participants to
`participants`	array	required	Array of user IDs to add to the conversation

Request

curl -X POST https://api.syncello.io/v1/tools/podio/addConversationParticipants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '{
  "conversation_id": "123",
  "participants": "..."
}'

Response

[
  {
    "user_id": 1122335,
    "profile_id": 4455668,
    "name": "John Smith",
    "type": "user"
  }
]

Try It

Try it

Leave Conversation

Read

POST /v1/tools/podio/leaveConversation

Leave a conversation. The authenticated user will be removed from the participant list and will no longer receive messages.

Parameters

Name	Type	Required	Description
`conversation_id`	number	required	The ID of the conversation to leave

Request

curl -X POST https://api.syncello.io/v1/tools/podio/leaveConversation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '{
  "conversation_id": "123"
}'

Response

{
  "left": true,
  "conversation_id": 58203417
}