Gladly Proactive Conversations API

openapi: 3.2.0
info:
  title: Gladly Proactive Conversations API
  version: '1.0'
  description: '# Introducing the Gladly API


    At Gladly, we believe that customer service is best when it''s a conversation.'
servers:
- url: https://{organization}.gladly.com/api/v1
  description: Production
  variables:
    organization:
      default: organization
      description: Your Gladly organization subdomain
- url: https://{organization}.gladly.qa/api/v1
  description: Sandbox
  variables:
    organization:
      default: organization
      description: Your Gladly QA organization subdomain
security:
- basicAuth: []
tags:
- name: Proactive Conversations
  description: A proactive conversation consists of a **campaign** and **recipients**. This APIs intended use-case would be to provide status updates to a customer and not for marketing purposes.
paths:
  /api/v1/campaigns/{campaignId}/recipient-collections:
    parameters:
    - name: campaignId
      in: path
      description: id of the campaign to create a new recipient collection for
      required: true
      schema:
        type: string
        example: yQ16L_YURROhXAg3KzkuYQ
    post:
      tags:
      - Proactive Conversations
      summary: Create Recipient Collection for an Existing Proactive Campaign
      description: 'Create a new recipient collection for an existing proactive campaign that will be contacted based on the campaign settings.


        You can locate the `campaignId` by navigating to the campaign in the dashboard and copying the `id` from the URL.'
      operationId: createRecipientCollection
      requestBody:
        content:
          application/json:
            schema:
              title: Recipient Collection Create Request
              description: Request payload for creating a new recipient collection
              type: object
              required:
              - name
              - startAfter
              - recipients
              properties:
                name:
                  type: string
                  description: Name for recipient collection
                  example: Delivery reminders
                startAfter:
                  type: string
                  format: RFC3339
                  description: The time after which the recipient collection should start processing
                  example: '2019-02-21T07:15:19.07272933Z'
                endBefore:
                  type: string
                  format: RFC3339
                  description: The time before which the recipient collection should stop processing
                  example: '2019-02-21T07:15:19.07272933Z'
                recipients:
                  type: array
                  items:
                    oneOf:
                    - title: Email Recipients
                      description: Email recipients for recipient collection request
                      type: object
                      required:
                      - customerName
                      - emailAddress
                      - timezone
                      properties:
                        customerName:
                          type: string
                          description: Name of customer
                          example: Jane Smith
                        emailAddress:
                          type: string
                          description: Email address for the customer
                          example: jane.smith@example.com
                        timezone:
                          type: string
                          description: Timezone the customer is located in. Supported timezones are those found in the IANA timezone database.
                          example: America/Los_Angeles
                    - title: SMS Recipients
                      description: SMS recipients for recipient collection request
                      type: object
                      required:
                      - customerName
                      - phoneNumber
                      - timezone
                      properties:
                        customerName:
                          type: string
                          description: Name of customer
                          example: Jane Smith
                        phoneNumber:
                          type: string
                          description: Phone Number for the customer
                          example: (415) 555-1234
                        timezone:
                          type: string
                          description: Timezone the customer is located in. Supported timezones are those found in the IANA timezone database.
                          example: America/Los_Angeles
                    - title: Voice Recipients
                      description: Voice recipients for recipient collection request
                      type: object
                      required:
                      - customerName
                      - phoneNumber
                      - timezone
                      properties:
                        customerName:
                          type: string
                          description: Name of customer
                          example: Jane Smith
                        phoneNumber:
                          type: string
                          description: Phone Number for the customer
                          example: (415) 555-1234
                        timezone:
                          type: string
                          description: Timezone the customer is located in. Supported timezones are those found in the IANA timezone database.
                          example: America/Los_Angeles
            examples:
              Email Recipient Collection:
                summary: Create recipient collection with email recipients
                value:
                  name: Email collection
                  startAfter: '2024-05-13T16:32:00.000Z'
                  recipients:
                  - customerName: John Baker
                    emailAddress: john.baker@example.com
                    timezone: America/Los_Angeles
                  - customerName: Jane Smith
                    emailAddress: jane.smith@example.com
                    timezone: America/New_York
              SMS Recipient Collection:
                summary: Create recipient collection with sms recipients
                value:
                  name: SMS collection
                  startAfter: '2024-05-13T16:32:00.000Z'
                  recipients:
                  - customerName: John Baker
                    phoneNumber: '+14155551234'
                    timezone: America/Los_Angeles
                  - customerName: Jane Smith
                    phoneNumber: (212) 555-9876
                    timezone: America/New_York
              Voice Recipient Collection:
                summary: Create recipient collection with voice recipients
                value:
                  name: Voice collection
                  startAfter: '2024-05-13T16:32:00.000Z'
                  recipients:
                  - customerName: John Baker
                    phoneNumber: '+14155551234'
                    timezone: America/Los_Angeles
                  - customerName: Jane Smith
                    phoneNumber: (212) 555-9876
                    timezone: America/New_York
      responses:
        '200':
          description: created recipient collection
          content:
            application/json:
              schema:
                title: Recipient Collection
                description: Recipient Collection
                type: object
                required:
                - id
                - campaignId
                - type
                - startAfter
                - name
                - status
                properties:
                  id:
                    type: string
                    description: Unique recipient collection id
                    example: oiaFOojmQu2v8CRQaVUIjw
                  campaignId:
                    type: string
                    description: Campaign id the recipient collection belongs to
                    example: qmkz789yRyO6BdC8WeEitA
                  type:
                    type: string
                    description: Type of recipient collection
                    example: EMAIL
                    enum:
                    - EMAIL
                    - SMS
                    - VOICE
                  startAfter:
                    type: string
                    format: RFC3339
                    description: The time after which the recipient collection should start processing
                    example: '2019-02-21T07:15:19.07272933Z'
                  endBefore:
                    type: string
                    format: RFC3339
                    description: The time before which the recipient collection should stop processing
                    example: '2019-02-21T07:15:19.07272933Z'
                  name:
                    type: string
                    description: Name of the recipient collection
                    example: My Collection
                  status:
                    type: string
                    description: Status of the recipient collection
                    example: ACTIVE
                    enum:
                    - ACTIVE
                    - CANCELED
                    - COMPLETED
                    - PENDING
                    - SCHEDULED
        '404':
          description: campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrors'
components:
  schemas:
    NotFoundErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          example:
          - code: not_exist
            detail: entity does not exist
    Error:
      type: object
      properties:
        attr:
          type: string
          description: Identifies the field causing the error
        code:
          type: string
          description: Code indicating the error type
        detail:
          type: string
          description: More details describing what went wrong
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'Gladly API uses token-based **Basic Authentication**. API tokens are associated with designated Gladly users.

        To create and use an API token, your user must have the API User permission. An API token can be used to perform any API request without restriction.


        | user name   | password  |

        | ----------- | --------- |

        | agent email | API token |


        The credentials must be passed via an `Authorization` HTTP header. All requests must be made over HTTPS.


        ```shell

        curl -u user@organization.com:$GLADLY_API_TOKEN \

        https://organization.gladly.com/api/v1/organization

        ```

        '
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth — username is the API user email; password is the API token. Requires the "API User" permission.
x-tagGroups:
- name: REST API
  tags:
  - Agents
  - Public Answer
  - Answer Management
  - Audiences
  - Business Hours
  - Communications
  - Conversations
  - Customers
  - Events
  - Export
  - Freeform Topics
  - Inboxes
  - Organization
  - Proactive Conversations
  - Reports
  - Tasks
  - Teams
  - User Identity
  - Topics
  - Webhooks
- name: Webhooks
  tags:
  - Summary
  - Payloads
- name: Lookup API
  tags:
  - Customer Lookup
- name: Resources
  tags:
  - Versioning
  - Error Handling
  - Rate Limit
  - Rich Content
  - Launching Soon