Gladly Communications API

openapi: 3.2.0
info:
  title: Gladly Communications 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: Communications
  description: 'Communications API enables you to programmatically send messages to your customers. These messages are non-routable and non-searchable.


    ### Agent View

    !Agent View


    ### Consumer View

    !Customer View'
paths:
  /api/v1/communications/sms:
    post:
      tags:
      - Communications
      summary: Send SMS
      description: 'To send an SMS message to a customer specified by a mobile phone number.


        Gladly can send outbound SMS messages globally. By default, your organization is set up to only allow access to your home country. To send SMS messages to other countries, please contact Gladly Support with a P4 designation.


        Please be aware that:

        - Any automated outbound text messages **must** comply with carrier acceptable use policies (e.g.: if sending automated messages about order status, make sure customers can explicitly opt-in to text messages), including registering your SMS use cases carriers.

        - Text messages send in segments and you pay per segment. We highly recommend using the segment calculator when crafting automated outbound text messages.

        - Each type of phone number has a Message Segments per Second limit.'
      operationId: sendSMS
      requestBody:
        description: SMS to send
        content:
          application/json:
            schema:
              title: SMS request body
              required:
              - customer
              - from
              - body
              type: object
              properties:
                customer:
                  title: customer with mobile number
                  required:
                  - mobileNumber
                  type: object
                  properties:
                    mobileNumber:
                      $ref: '#/paths/~1api~1v1~1communications~1sms/post/requestBody/content/application~1json/schema/properties/from'
                from:
                  title: mobile number
                  type: string
                  example: '+14152223316'
                body:
                  title: SMS message
                  type: string
                  example: hello, this is an SMS message!
            example:
              customer:
                mobileNumber: '+14152223000'
              from: '+14152223316'
              body: hello, this is a sample SMS message!
        required: true
      responses:
        '200':
          description: the customer and conversation item ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  customerId:
                    type: string
                    description: customer ID
                    example: gHufx-U3QqOmhvFuViceTw
                  conversationItemId:
                    type: string
                    description: conversation item ID of the SMS
                    example: pOVVdzweSumI4bFxjlT8LA
        '400':
          description: Invalid field(s) in request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /api/v1/communications/email:
    post:
      tags:
      - Communications
      summary: Send Email
      description: 'Used to send an email messages to a customer specified by an email address.


        Any items created using this API will not be considered part of a conversation, and are **non-routable** and **non-searchable** aside from the email address specified as part of the payload.'
      operationId: sendEmail
      requestBody:
        description: Email to send
        content:
          application/json:
            schema:
              title: Email request body
              required:
              - to
              - from
              - subject
              - body
              type: object
              properties:
                to:
                  description: Email addresses to send the email to. Currently, only one email address is supported. The email address and name will be used to find or create the customer.
                  type: array
                  items:
                    type: object
                    properties:
                      email:
                        type: string
                      name:
                        type: string
                      example:
                        email: jane.doe@example.com
                        name: Jane Doe
                from:
                  description: Email address to send the email from. This must be a configured email address in your organization.
                  type: string
                  example: no-reply@gladly.com
                subject:
                  type: string
                  description: Subject of the email. Must be less than 1000 characters.
                  example: This is a sample email message!
                body:
                  description: Content of the email.
                  type: object
                  properties:
                    html:
                      type: string
                      description: HTML content of the email.
                      example: <div><p>This is a sample email message!</p><p>Best regards,<br>The Support Team</p></div>
                    text:
                      type: string
                      description: Plain text content of the email.
                      example: 'This is a sample email message!


                        Best regards,

                        The Support Team'
                  example:
                    html: <div><p>This is a sample email message!</p><p>Best regards,<br>The Support Team</p></div>
                    text: 'This is a sample email message!


                      Best regards,

                      The Support Team'
            example:
              to:
              - email: jane.doe@example.com
                name: Jane Doe
              from: no-reply@gladly.com
              subject: This is a sample email message!
              body:
                html: <div><p>This is a sample email message!</p><p>Best regards,<br>The Support Team</p></div>
                text: This is a sample email message!\n\nBest regards,\nThe Support Team
        required: true
      responses:
        '200':
          description: the customer and conversation item ID
          content:
            application/json:
              schema:
                $ref: '#/paths/~1api~1v1~1communications~1sms/post/responses/200/content/application~1json/schema'
        '400':
          description: Invalid field(s) in request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
components:
  schemas:
    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
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          example:
          - attr: content
            code: blank
            detail: content cannot be blank
  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