openapi: 3.0.1 info: title: Pipedrive API v1 Activities Channels API version: 1.0.0 description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time. ' servers: - url: https://api.pipedrive.com/v1 tags: - name: Channels description: 'Channels API allows you to integrate your existing messaging channels into Pipedrive through [Messaging app extension](https://pipedrive.readme.io/docs/messaging-app-extension). It enables you to manage and interact with the channel’s conversations, participants and messages inside Pipedrive Messaging inbox: get the historical conversation, receive and send new messages. These endpoints are accessible only through **Messengers integration** OAuth scope together with Messaging manifest in building the [Messaging app extension](https://pipedrive.readme.io/docs/messaging-app-extension). ' paths: /channels: post: deprecated: true security: - api_key: [] - oauth2: - messengers-integration tags: - Channels summary: Add a channel description: Adds a new messaging channel, only admins are able to register new channels. It will use the getConversations endpoint to fetch conversations, participants and messages afterward. To use the endpoint, you need to have **Messengers integration** OAuth scope enabled and the Messaging manifest ready for the [Messaging app extension](https://pipedrive.readme.io/docs/messaging-app-extension). x-token-cost: 10 operationId: addChannel requestBody: content: application/json: schema: type: object required: - name - provider_channel_id properties: name: type: string example: My Channel description: The name of the channel provider_channel_id: type: string description: The channel ID avatar_url: type: string format: url description: The URL for an icon that represents your channel template_support: type: boolean description: If true, enables templates logic on UI. Requires getTemplates endpoint implemented. Find out more [here](https://pipedrive.readme.io/docs/implementing-messaging-app-extension). default: false provider_type: type: string enum: - facebook - whatsapp - other default: other description: It controls the icons (like the icon next to the conversation) responses: '200': description: The channel registered content: application/json: schema: type: object title: AddChannelResponse properties: success: type: boolean example: true data: type: object properties: id: type: string description: The unique channel ID used internally in omnichannel-api and the frontend of the extension name: type: string example: My Channel description: The name of the channel avatar_url: type: string example: http://some-domain.com/test.jpg description: The URL for an icon that represents your channel provider_channel_id: type: string format: string description: The channel ID you specified while creating the channel marketplace_client_id: type: string description: The client_id of your app in Pipedrive marketplace pd_company_id: type: integer example: 1 description: The ID of the user's company in Pipedrive pd_user_id: type: integer example: 1 description: The ID of the user in Pipedrive created_at: type: string format: date-time description: The date and time when your channel was created in the API provider_type: type: string enum: - facebook - whatsapp - other description: Value of the provider_type sent to this endpoint template_support: type: boolean description: Value of the template_support sent to this endpoint example: success: true data: id: e283f878-7ef9-4294-8e5c-04a7d003fd92 name: My Channel avatar_url: http://my-domain.com/images/test.png provider_channel_id: e283f878-7ef9-4294-8e5c-04a7d003fd92 marketplace_client_id: 57da5c3c55a82bb4 pd_company_id: 123 pd_user_id: 321 created_at: '2022-03-01 00:00:00' provider_type: other template_support: false '400': description: Bad Request content: application/json: schema: type: object title: AddChannelBadRequestResponse properties: success: type: boolean example: false error: type: string example: 'Expected { name: string; avatar_url?: string; provider_channel_id: string; }, but was incompatible' description: The error description error_info: type: string example: Please check the reference docs in https://developers.pipedrive.com/docs/api/v1 additional_data: type: object properties: code: type: string example: INVALID_BODY description: An error code sent by the API '403': description: Forbidden content: application/json: schema: type: object title: AddChannelForbiddenErrorResponse properties: success: type: boolean example: false error: type: string example: Only admins can register channels description: The error description error_info: type: string example: Please check the reference docs in https://developers.pipedrive.com/docs/api/v1 additional_data: type: object properties: code: type: string example: ADMIN_ONLY description: An error code sent by the API /channels/{id}: delete: deprecated: true security: - api_key: [] - oauth2: - messengers-integration tags: - Channels summary: Delete a channel description: Deletes an existing messenger’s channel and all related entities (conversations and messages). To use the endpoint, you need to have **Messengers integration** OAuth scope enabled and the Messaging manifest ready for the [Messaging app extension](https://pipedrive.readme.io/docs/messaging-app-extension). x-token-cost: 6 operationId: deleteChannel parameters: - in: path name: id schema: type: string required: true description: The ID of the channel provided by the integration responses: '200': description: The channel was deleted content: application/json: schema: type: object properties: success: type: boolean example: true example: success: true '400': description: Bad Request content: application/json: schema: type: object title: AddChannelBadRequestResponse properties: success: type: boolean example: false error: type: string example: 'Expected { name: string; avatar_url?: string; provider_channel_id: string; }, but was incompatible' description: The error description error_info: type: string example: Please check the reference docs in https://developers.pipedrive.com/docs/api/v1 additional_data: type: object properties: code: type: string example: INVALID_BODY description: An error code sent by the API /channels/messages/receive: post: deprecated: true security: - api_key: [] - oauth2: - messengers-integration tags: - Channels summary: Receives an incoming message description: Adds a message to a conversation. To use the endpoint, you need to have **Messengers integration** OAuth scope enabled and the Messaging manifest ready for the [Messaging app extension](https://pipedrive.readme.io/docs/messaging-app-extension). x-token-cost: 10 operationId: receiveMessage requestBody: content: application/json: schema: type: object required: - id - channel_id - sender_id - conversation_id - message - status - created_at properties: id: type: string description: The ID of the message channel_id: type: string description: The channel ID as in the provider sender_id: type: string description: The ID of the provider's user that sent the message conversation_id: type: string description: The ID of the conversation message: type: string description: The body of the message status: type: string enum: - sent - delivered - read - failed description: The status of the message created_at: type: string format: date-time description: 'The date and time when the message was created in the provider, in UTC. Format: YYYY-MM-DD HH:MM' reply_by: type: string format: date-time description: 'The date and time when the message can no longer receive a reply, in UTC. Format: YYYY-MM-DD HH:MM' conversation_link: type: string format: url description: A URL that can open the conversation in the provider's side attachments: type: array description: The list of attachments available in the message items: type: object required: - id - type - url properties: id: type: string description: The ID of the attachment type: type: string description: The mime-type of the attachment name: type: string description: The name of the attachment size: type: number description: The size of the attachment url: type: string description: A URL to the file preview_url: type: string description: A URL to a preview picture of the file link_expires: type: boolean default: false description: If true, it will use the getMessageById endpoint for fetching updated attachment's urls. Find out more [here](https://pipedrive.readme.io/docs/implementing-messaging-app-extension) responses: '200': description: The message was registered in the conversation content: application/json: schema: title: GetReceiveMessageSuccessResponse type: object properties: success: type: boolean description: If the request was successful or not data: type: object required: - id - channel_id - sender_id - conversation_id - message - status - created_at properties: id: type: string description: The ID of the message channel_id: type: string description: The channel ID as in the provider sender_id: type: string description: The ID of the provider's user that sent the message conversation_id: type: string description: The ID of the conversation message: type: string description: The body of the message status: type: string enum: - sent - delivered - read - failed description: The status of the message created_at: type: string format: date-time description: 'The date and time when the message was created in the provider, in UTC. Format: YYYY-MM-DD HH:MM' reply_by: type: string format: date-time description: 'The date and time when the message can no longer receive a reply, in UTC. Format: YYYY-MM-DD HH:MM' conversation_link: type: string format: url description: A URL that can open the conversation in the provider's side attachments: type: array description: The list of attachments available in the message items: type: object required: - id - type - url properties: id: type: string description: The ID of the attachment type: type: string description: The mime-type of the attachment name: type: string description: The name of the attachment size: type: number description: The size of the attachment url: type: string description: A URL to the file preview_url: type: string description: A URL to a preview picture of the file link_expires: type: boolean default: false description: If true, it will use the getMessageById endpoint for fetching updated attachment's urls. Find out more [here](https://pipedrive.readme.io/docs/implementing-messaging-app-extension) example: success: true data: id: e283f878-7ef9-4294-8e5c-04a7d003fd92 channel_id: a8aa4db0-91bb-4e90-b9c0-0c6291307e2f sender_id: 5d4bd467-d847-4088-ae43-0c7614233bab conversation_id: 063ffa46-831c-4027-a04c-b65e17f077b7 message: This is a message status: sent created_at: '2022-03-01T07:58:35.449Z' reply_by: '2022-03-01T07:58:35.449Z' conversation_link: http://my-server.com/conversations/063ffa46-831c-4027-a04c-b65e17f077b7 attachments: - id: b0369d1d-6b6a-4293-88b9-e2924782d47e type: image/png name: Image Name size: 600 url: http://my-server.com/images/b0369d1d-6b6a-4293-88b9-e2924782d47e.png preview_url: http://my-server.com/images/b0369d1d-6b6a-4293-88b9-e2924782d47e.preview.png '400': description: Bad Request content: application/json: schema: title: ReceiveMessageBadRequestErrorResponse type: object properties: success: type: boolean example: false error: type: string example: 'Expected { id: string; sender_id: string; conversation_id: string; conversation_link?: string; channel_id: string; created_at: string; message: string; status: unknown; attachments: { id: string; type: string; name: string | null; size: number | null; url: string; preview_url: string | null; }[]; reply_by?: string | null; }, but was incompatible' description: The error description error_info: type: string example: Please check the reference docs in https://developers.pipedrive.com/docs/api/v1 additional_data: type: object properties: code: type: string example: INVALID_RECEIVE_MESSAGE_PAYLOAD description: An error code sent by the API /channels/{channel-id}/conversations/{conversation-id}: delete: deprecated: true security: - api_key: [] - oauth2: - messengers-integration tags: - Channels summary: Delete a conversation description: Deletes an existing conversation. To use the endpoint, you need to have **Messengers integration** OAuth scope enabled and the Messaging manifest ready for the [Messaging app extension](https://pipedrive.readme.io/docs/messaging-app-extension). x-token-cost: 6 operationId: deleteConversation parameters: - in: path name: channel-id schema: type: string required: true description: The ID of the channel provided by the integration - in: path name: conversation-id schema: type: string required: true description: The ID of the conversation provided by the integration responses: '200': description: The conversation was deleted content: application/json: schema: type: object properties: success: type: boolean example: true example: success: true '403': description: Forbidden content: application/json: schema: type: object title: DeleteConversationForbiddenErrorResponse properties: success: type: boolean example: false error: type: string example: Only the app owner can delete conversations description: The error description error_info: type: string example: Please check the reference docs in https://developers.pipedrive.com/docs/api/v1 additional_data: type: object properties: code: type: string example: FORBIDDEN_USER_REQUEST description: An error code sent by the API '404': description: Not Found content: application/json: schema: type: object title: DeleteConversationNotFoundErrorResponse properties: success: type: boolean example: false error: type: string example: Channel not found. description: The error description error_info: type: string example: Please check the reference docs in https://developers.pipedrive.com/docs/api/v1 additional_data: type: object properties: code: type: string example: NOT_FOUND description: An error code sent by the API components: securitySchemes: basic_authentication: type: http scheme: basic description: Base 64 encoded string containing the `client_id` and `client_secret` values. The header value should be `Basic `. api_key: type: apiKey name: x-api-token in: header oauth2: type: oauth2 description: For more information, see https://pipedrive.readme.io/docs/marketplace-oauth-authorization flows: authorizationCode: authorizationUrl: https://oauth.pipedrive.com/oauth/authorize tokenUrl: https://oauth.pipedrive.com/oauth/token refreshUrl: https://oauth.pipedrive.com/oauth/token scopes: base: Read settings of the authorized user and currencies in an account deals:read: Read most of the data about deals and related entities - deal fields, products, followers, participants; all notes, files, filters, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal) deals:full: Create, read, update and delete deals, its participants and followers; all files, notes, and filters. It also includes read access to deal fields, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal) mail:read: Read mail threads and messages mail:full: Read, update and delete mail threads. Also grants read access to mail messages activities:read: Read activities, its fields and types; all files and filters activities:full: Create, read, update and delete activities and all files and filters. Also includes read access to activity fields and types contacts:read: Read the data about persons and organizations, their related fields and followers; also all notes, files, filters contacts:full: Create, read, update and delete persons and organizations and their followers; all notes, files, filters. Also grants read access to contacts-related fields products:read: Read products, its fields, files, followers and products connected to a deal products:full: Create, read, update and delete products and its fields; add products to deals deal-fields:full: Create, read, update and delete deal fields product-fields:full: Create, read, update and delete product fields contact-fields:full: Create, read, update and delete person and organization fields projects:read: Read projects and its fields, tasks and project templates projects:full: Create, read, update and delete projects and its fields; add projects templates and project related tasks users:read: Read data about users (people with access to a Pipedrive account), their permissions, roles and followers recents:read: Read all recent changes occurred in an account. Includes data about activities, activity types, deals, files, filters, notes, persons, organizations, pipelines, stages, products and users search:read: Search across the account for deals, persons, organizations, files and products, and see details about the returned results admin: Allows to do many things that an administrator can do in a Pipedrive company account - create, read, update and delete pipelines and its stages; deal, person and organization fields; activity types; users and permissions, etc. It also allows the app to create webhooks and fetch and delete webhooks that are created by the app leads:read: Read data about leads and lead labels leads:full: Create, read, update and delete leads and lead labels phone-integration: Enables advanced call integration features like logging call duration and other metadata, and play call recordings inside Pipedrive goals:read: Read data on all goals goals:full: Create, read, update and delete goals video-calls: Allows application to register as a video call integration provider and create conference links messengers-integration: Allows application to register as a messengers integration provider and allows them to deliver incoming messages and their statuses