Regal Messages API

openapi: 3.2.0
info:
  title: contact-center-apis Messages API
  version: '1.2'
servers:
- url: https://api.regal.ai/v1
security:
- sec0: []
tags:
- name: Messages
paths:
  /messages/send:
    post:
      summary: Send Message
      description: Send messages at scale.
      operationId: send-message
      parameters:
      - name: Authorization
        in: header
        description: Your Regal API Key
        required: true
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
          default: application/json
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - to
              - channel
              properties:
                to:
                  type: object
                  description: The message recipient.
                  required:
                  - phoneNumber
                  properties:
                    phoneNumber:
                      type: string
                      description: Valid phone number of the recipient.
                    bypassOptIn:
                      type: boolean
                      description: Whether to send the message even if the recipient has not opted in to SMS. If false (default if omitted), the message will only be sent if the contact is opted in. If campaignId is provided and to.bypassOptIn is omitted, the campaign’s bypass setting will be used.
                      default: false
                from:
                  type: object
                  description: The message sender.
                  required:
                  - phoneNumber
                  properties:
                    phoneNumber:
                      type: string
                      description: Phone number belonging to your brand
                channel:
                  type: string
                  description: The communication channel.
                  enum:
                  - '"sms"'
                content:
                  type: object
                  description: The message content.
                  required:
                  - body
                  properties:
                    body:
                      type: string
                      description: The message's content (up to 1600 characters)
                    mediaUrls:
                      type: array
                      description: The image attachment for the message. If provided, this must be an array with a maximum of one valid image URL. Multiple attachments are not supported.
                      items:
                        type: string
                campaignId:
                  type: integer
                  description: If an SMS campaign is provided, the campaign supplies default content, from number, and opt-in behavior. Any values included in the request (via content, from, or to.bypassOptIn) override the campaign defaults.
                  format: int32
      responses:
        '202':
          description: '202'
          content:
            application/json:
              examples:
                Response Data:
                  value: "{\n    \"status\": \"queued\",\n    \"message\": \"enqueued for sms-interaction-job\",\n    \"idempotencyKey\": \"80d65f2f3832ffeed65346056bab1cd8\"\n}"
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: queued
                  message:
                    type: string
                    example: enqueued for sms-interaction-job
                  idempotencyKey:
                    type: string
                    example: 80d65f2f3832ffeed65346056bab1cd8
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Bad Request:
                  value: "{\n    \"statusCode\": 400,\n    \"message\": [\n        \"channel must be one of the following values: 'sms'\",\n        \"to should not be empty\",\n        \"'content' is required when 'campaignId' is not provided.\"\n    ],\n    \"error\": \"Bad Request\"\n}"
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 400
                    default: 0
                  message:
                    type: array
                    items:
                      type: string
                      example: 'channel must be one of the following values: ''sms'''
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: '401'
          content:
            application/json:
              examples:
                Unauthorized:
                  value: "{\n    \"message\": \"Unauthorized\"\n}"
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
        '403':
          description: '403'
          content:
            application/json:
              examples:
                Result:
                  value: "{\n    \"statusCode\": 403,\n    \"message\": \"Invalid API Key\",\n    \"error\": \"Forbidden\"\n}"
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 403
                    default: 0
                  message:
                    type: string
                    example: Invalid API Key
                  error:
                    type: string
                    example: Forbidden
        '429':
          description: '429'
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  value: "{\n  \"message\":\"Too Many Requests\"\n}"
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too Many Requests
      x-readme:
        code-samples:
        - language: curl
          code: "curl --location 'https://api.regal.ai/v1/messages/send' \\\n--header 'Authorization: YOUR API KEY' \\\n--header 'Content-Type: application/json' \\\n--data '{\n    \"to\": {\n      \"phoneNumber\": \"800‑555‑0100\",\n      \"bypassOptIn\": true\n    },\n    \"channel\": \"sms\",\n    \"content\": {\n      \"body\": \"Your appointment is confirmed for tomorrow!\",\n      \"mediaUrls\": [\"http://github.com/regal-voice.png\"]\n    }\n  }'"
        samples-languages:
        - curl
      tags:
      - Messages
components:
  securitySchemes:
    sec0:
      type: apiKey
      name: Authorization
      in: header