List conversations

curl --request GET \
  --url https://api.partoo.co/v2/conversations \
  --header 'x-APIKey: <api-key>'

{
  "conversations": [
    {
      "id": 123,
      "consumer_img": "https://www.example.com/profile-picture.jpg",
      "consumer_name": "John Doe",
      "consumer_phone_number": "+33612345678",
      "last_message": "<unknown>",
      "is_read": true,
      "status": "Open",
      "created_at": "2023-01-31 16:22:17.327878+00:00",
      "has_one_user_message": true,
      "business": {
        "id": "<string>",
        "name": "<string>",
        "city": "<string>",
        "zipcode": "<string>",
        "country": "<string>",
        "formatted_address": "<string>"
      },
      "messaging_partner": "Facebook",
      "issues": [
        "facebook_no_page_linked"
      ],
      "first_message_date": "<string>",
      "is_expired": false,
      "is_solved": false,
      "assigned_user_id": "62d80fae74e8b11d700302b8",
      "custom_channel": "<unknown>"
    }
  ],
  "count": 1,
  "next_cursor": "<string>"
}

Messages

List conversations

This endpoint lets you list all the Conversations you have access to.

You can filter the conversations based on the Organization or the Business that they are related to.

If you want to keep an up-to-date list of ongoing conversations for your businesses, we recommend using the Message Received and Message Deleted Webhooks instead of periodically calling this endpoint.

⚠️ This endpoint is paginated using cursor pagination. This means that in order to get the next page of results, you need to provide the cursor returned in the previous call.

GET

conversations

List conversations

curl --request GET \
  --url https://api.partoo.co/v2/conversations \
  --header 'x-APIKey: <api-key>'

{
  "conversations": [
    {
      "id": 123,
      "consumer_img": "https://www.example.com/profile-picture.jpg",
      "consumer_name": "John Doe",
      "consumer_phone_number": "+33612345678",
      "last_message": "<unknown>",
      "is_read": true,
      "status": "Open",
      "created_at": "2023-01-31 16:22:17.327878+00:00",
      "has_one_user_message": true,
      "business": {
        "id": "<string>",
        "name": "<string>",
        "city": "<string>",
        "zipcode": "<string>",
        "country": "<string>",
        "formatted_address": "<string>"
      },
      "messaging_partner": "Facebook",
      "issues": [
        "facebook_no_page_linked"
      ],
      "first_message_date": "<string>",
      "is_expired": false,
      "is_solved": false,
      "assigned_user_id": "62d80fae74e8b11d700302b8",
      "custom_channel": "<unknown>"
    }
  ],
  "count": 1,
  "next_cursor": "<string>"
}

Authorizations

x-APIKey

string

header

required

The authentication system on Partoo API is using API Key that should be put in the header of the request (the name of the header is x-APIKey). An api_key is linked to a user. This user's role will give you different access level to the API features.

Query Parameters

per_page

integer

default:30

Number of items to return per page.

Required range: 1 <= x <= 100

cursor

string

The cursor identifiying the page of data to fetch. If no cursor is provided, the query will return the first page of data. A cursor for the next page of data is provided in the response of this request.

business__in

string[]

Filter by business ids. Use a comma-separated list to provide multiple ids.

Example:

"a1c9f37b4deca92f83b61d02,9f4e2a8c0d73b154e621bc97,c73b15e9fa42d60b3a8c21ef"

Response

Response object

conversations

Conversation · object[]

The list of conversations, paginated.

Show child attributes

conversations.id

integer

conversations.consumer_img

string<url> | null

The url of the consumer's profile picture

Example:

"https://www.example.com/profile-picture.jpg"

conversations.consumer_name

string | null

The name of the consumer, can be empty. The format may differ depending on the platform of contact (ex: "John Doe", "John Doe (@johndoe)", "@johndoe", "", ...).

Example:

"John Doe"

conversations.consumer_phone_number

string | null

The phone number of the consumer, formatted in E.164 international format (ex: "+33612345678").

Example:

"+33612345678"

conversations.last_message

Message · object

The last message exchanged in the conversation.

Show child attributes

conversations.last_message.id

integer

The id of the message.

conversations.last_message.conversation_id

integer

The id of the parent conversation.

conversations.last_message.date

string

The date at which the message was sent or received, in the ISO 8601 format (ex: "2023-01-31 16:22:17.327878+00:00").

Example:

"2023-01-31 16:22:17.327878+00:00"

conversations.last_message.content_type

enum<string>

The type of the message:

"Text" describes a simple text message.
"Image" describes a message that only contains an image.
"IgStoryReply" (for "Instagram" conversations) describes a notification of reply to an Instagram story.
"IgStoryMention" (for "Instagram" conversations) describes a notification of a mention in an Instagram story.
"Unsupported" describes a message whose content is not supported.

⚠️ New values may be added to this enum without prior notice and without following the classic depreciation cycle.
It is up to you to gracefully handle the case where new values are added.
We recommend showing a "Unhandled content" placeholder to the user in place of the message ⚠️

Available options:

Text,

Image,

Video,

Audio,

Document,

IgStoryReply,

IgStoryMention,

Unsupported

conversations.last_message.sender_type

enum<string>

Describes the person that sent the Message:

"User" indicates that the message was sent as the Business. Such messages can be sent by a Partoo user, via API, or directly on the messaging platform.
"Consumer" indicates that the message was sent by a consumer, a client that wants to get in touch with the business.
"Metadata" is reserved for special messages that appear in the Partoo inbox. They only give contextual information about the conversation, and are not shown to the consumer.

⚠️ New values may be added to this enum without prior notice and without following the classic depreciation cycle.
It is up to you to gracefully handle the case where new values are added.
We recommend ignoring messages with unhandled sender_type ⚠️

Available options:

User,

Consumer,

Metadata

conversations.last_message.sender_label

string | null

Name of the person sending the message

Example:

"Jane Doe"

conversations.last_message.status

enum<string>

The delivery status of the message. Messages send via Partoo are created with the status "Sending", and propagated to the messaging channel. If the message is sent successfully, the status is changed to "Success". If the messaging channel fails to send the message, the status changed to "Failed". A failed message can be retried using the /retry endpoint.

Available options:

Sending,

Success,

Failed

conversations.last_message.is_deleted

boolean

If the message has been deleted by the consumer on the messaging channel (for now, only "Instagram" messages can be deleted).

Example:

false

conversations.last_message.content

The text of the message.

conversations.last_message.user_id

string | null

For "User" messages sent via the Partoo application, the id of the user that sent the message.

conversations.last_message.custom_channel

Message · object

Data about the custom channel, this object is filled only if the messaging partner is Custom.

Show child attributes

conversations.last_message.custom_channel.external_message_id

string

The unique id of the message in your system.

conversations.is_read

boolean

If the last message received was read.
This property is scoped to the user who performs the request. Multiple partoo users can have a different is_read value for the same conversation.

conversations.status

enum<string>

If Open, it is possible to send a message in the conversation, else not. A conversation can be Closed if it is expired.

Available options:

Open,

Closed

conversations.created_at

string

The date of creation of the conversation, in the ISO 8601 format (ex: "2023-01-31 16:22:17.327878+00:00").

Example:

"2023-01-31 16:22:17.327878+00:00"

conversations.has_one_user_message

boolean

If the conversation has at least one message sent by a Partoo user.

conversations.business

BusinessInfo · object

Some basic information about the business that the conversation is associated with.

Show child attributes

conversations.business.id

string

conversations.business.name

string | null

conversations.business.city

string | null

conversations.business.zipcode

string | null

conversations.business.country

string | null

conversations.business.formatted_address

string | null

conversations.messaging_partner

enum<string>

The channel that the message is being sent to/from.

⚠️ New values may be added to this enum without prior notice and without following the classic depreciation cycle.
It is up to you to gracefully handle the case where new values are added.

Available options:

Google,

Facebook,

Instagram,

SMS,

Whatsapp

Example:

"Facebook"

conversations.issues

enum<string>[]

The list of issues that affect the conversation. The issues represent setup problem that the business may have with a messaging channel. It is not possible to send messages on a conversation that has issues.

⚠️ New values may be added to this enum without prior notice and without following the classic depreciation cycle.
It is up to you to gracefully handle the case where new values are added.

Available options:

facebook_no_page_linked,

facebook_partner_co_undone,

facebook_invalid_status,

facebook_missing_webhook_subs,

instagram_no_account_linked,

sms_no_phone_number

Example:

["facebook_no_page_linked"]

conversations.first_message_date

string

The date at which the first message of the conversation was received, in the ISO 8601 format (ex: "2023-01-31 16:22:17.327878+00:00").

conversations.is_expired

boolean

If the conversation has expired. A conversation expires if the consumer has not contacted the business for a certain amount of time.
You cannot send messages to an expired conversation.

Example:

false

conversations.is_solved

boolean

If the conversation has been solved.
Conversations can be solved from our app or by updating conversation status to "closed".

Example:

false

conversations.assigned_user_id

string

The "user_id" of the user assigned to the conversation.

Example:

"62d80fae74e8b11d700302b8"

conversations.custom_channel

Message · object

Data about the custom channel, this object is filled only if the messaging partner is Custom.

Show child attributes

conversations.custom_channel.id

string

The id of the custom channel.

conversations.custom_channel.name

string

The name of the custom channel.

conversations.custom_channel.icon

string

Url of the channel's icon.

conversations.custom_channel.is_readonly

boolean

Set to true if the channel to be read-only (i.e., no replies via Partoo)

conversations.custom_channel.external_conversation_id

string

The unique id of the conversation in your system.

count

integer

Total number of results available for the filters and dimensions requested.

Example:

1

next_cursor

string | null

The cursor to use in order to retrieve the next page of data. When all data have been fetched, the value is null.

Check connection token Conversation information

ApiKeys

Businesses

Business Fields

Categories

Connection Tokens

Messages

Custom Channels

Message Reply Templates

Messaging Settings

Custom Fields

Custom Fields Section

Custom Roles

Google

Groups and Sections

Holidays

Organizations

Posts

Place Action Links

Presence

Reviews

Presence analytics

Review analytics

Review Booster

Subscriptions

Users

Feedback Management

Webhooks

Webhooks Events

List conversations

Authorizations

Query Parameters

Response