sms-api.yml

openapi: 3.0.0
info:
  description: "The SMS API is designed for integration partners to be able to send SMS messages and perform other actions related to SMS through the CloudCall platform"
  version: "1.0.0"
  title: "SMS API"
  contact:
    email: "integrations@cloudcall.com"
servers:
  - url: https://ng-api.{platform}.cloudcall.com/v3/sms
    variables:
      platform:
        default: uk
        description: The platform the customer is on, either uk or us
paths:
  /send/message:
    post:
      tags:
      - "sms"
      summary: "Send a single SMS Message"
      description: "An API endpoint to send a message directly to a crm or cloudcall contact through the CloudCall platform"
      operationId: "SingleSms"
      requestBody:
        description: "Send a single SMS message via the CloudCall platform to a particular contact"
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/ChannelId"
                - $ref: "#/components/schemas/PhoneNumber"
                - $ref: "#/components/schemas/CrmObjectInstanceId"
                - $ref: "#/components/schemas/ContactId"
      responses:
        400:
          description: "Request body should provide crmUserId and contactId or channelId"
        202:
          description: "Message was sent, but user might not have permissions to view SMS channel"
        403:
          $ref: '#/components/responses/UnauthorizedError'
  /send/broadcast:
    post:
      tags:
      - "Send a Broadcast/Group SMS Message"
      summary: "Send an SMS message to a group of crm or cloudcall contacts through the CloudCall platform"
      description: ""
      operationId: "sendBroadcastMessage"
      requestBody:
        description: "Post the sms conversation information to open it in Unify"
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/ChannelId"
      responses:
        400:
          description: "Request body should provide crmUserId and contactId or channelId"
        202:
          description: "Message was sent, but user might not have permissions to view SMS channel"
        403:
          $ref: '#/components/responses/UnauthorizedError'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Body:
      type: "object"
      required:
        - "body"
      properties:
        body:
          type: "string"
          example: "Hello World!"
          description: "The message body that you want to send"
    ChannelId:
      allOf:
        - $ref: '#/components/schemas/Body'
        - type: "object"
          required:
          - "channelId"
          properties:
            channelId:
              type: "string"
              example: "912345-1234"
              description: "The channel Id of the conversation we want to open"
    CrmObjectInstanceId:
      allOf:
        - $ref: '#/components/schemas/Body'
        - type: "object"
          required:
          - "crmObjectInstanceId"
          properties:
            crmObjectInstanceId:
              type: "string"
              example: "4321"
              description: "The Id of the contact within the CRM. This CRM Contact must have sync'ed to CloudCall before it can be sent a message."
    PhoneNumber:
      allOf:
        - $ref: '#/components/schemas/Body'
        - type: "object"
          required:
          - "phoneNumber"
          properties:
            phoneNumber:
              type: "string"
              example: "07123456789"
              description: "A phone number in either local or E164 format that you want to send to. This phone number does not have to be associated with a contact."
    ContactId:
      allOf:
        - $ref: '#/components/schemas/Body'
        - type: "object"
          required:
          - "contactId"
          properties:
            contactId:
              type: "number"
              example: 4321
              description: "The CloudCall ContactId for the customer"
  responses:
    UnauthorizedError:
      description: There is not a valid JWT token passed to the Authorization header
security:
  - bearerAuth: []