openapi: 3.0.3
info:
  title: Communications API
  contact:
    email: support@venturedsolutions.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 4.0.0
servers:
- url: https://m5apitesting.groupcall.com/
  description: Testing API (UK)
- url: https://m5api.groupcall.com/
  description: Live API (UK)
- url: https://apitesting.groupcall.com/
  description: Testing API (US)
- url: https://api.groupcall.com/
  description: Live API (US)
paths:
  /api/SendMessage_V3/PartnerRoute:
    post:
      tags:
      - Delivery APIs
      summary: Send
      description: "This action supports delivery of message content based on customer configured routing rules on a per contact basis. \n\nIn your request, you can include content for:\n\n* SMS\n* Email\n* Push Notification\n* Eduspot Timeline\n\nThis API method will examine the customer/recipient routing configuration and determine which content to deliver to each defined recipient, based on the customer's configuration in the Groupcall or Teachers2Parents platform.\n\nWhen working with schools, it is recommended to include content for all routes to ensure greatest flexibility based on the customer's configuration and local data.\n\nWhen identifying your recipient, prefer to use the IdaasId property. It is the unique person identifier in scope of the school obtained from Xporter Data. It can also be constructed with aconsistent prefix per person type and MISID. \n|PersonType|Prefix|\n|--|--|\n|Student|PL-|\n|Student Contact|PC-|\n|Staff|PWT-|\n\nWhen working with other organisations or anonymous recipients, provide content for the message type you intend to send eg SMS only.\n"
      operationId: send
      parameters:
      - name: Authorization
        in: header
        description: "Idaas {STS_TOKEN}"
        required: false
        schema:
          type: string
      requestBody:
        description: Send Message
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/messageData"
            example:
              messageData:
              - ClientRef: 5E4F539B-E2D1-4178-B31F-244E8E403A9F
                EmailSentFromName: Primary Test Demo
                EmailSentFromAddress: noreply@datatool.groupcall.com
                EmailReplyToAddress: partner@datatool.groupcall.com
                EmailSubject: '*Email* & SMS - Basic'
                EmailBody: "*Email* & SMS - Dear $Name$, you have been tested $Date$"
                XpressionsBody: Rich content message to appear in the app timeline feed
                NotificationMessage: Simple content for push notification
                SMSMessage: "$Firstname$ has not registered for school this morning, please provide a reason"
                CallbackUrl: https://apitesting.xporter.one/TryIt/Callback
                Recipients:
                - ClientId: C613474F-F849-4CBF-9C4D-440C59ECA61E
                  SendTo: "1,"
                  IdaasId: PL-4158
                  DynamicTokens:
                  - $Firstname$: James
              styleClass: TestPartner
      responses:
        "200":
          $ref: "#/components/responses/messageResponse"
        "400":
          description: "invalid input, object invalid"
      callbacks:
        messageResponse:
          '{$request.body#/messageData/[0]/CallbackUrl}':
            get:
              summary: Callback Request
              parameters:
              - name: sentid
                in: query
                description: The Communications internal id for this specific message
                required: false
                schema:
                  type: string
              - name: contactid
                in: query
                description: The Communications internal of the target contact
                required: false
                schema:
                  type: string
              - name: externalid
                in: query
                description: The MIS record ID of the target contact
                required: false
                schema:
                  type: string
              - name: clientref
                in: query
                description: The clientRef value that you specified in your call
                required: false
                schema:
                  type: string
              - name: recipient
                in: query
                description: The formatted mobile phone number used to address the contac
                required: false
                schema:
                  type: string
              - name: status
                in: query
                description: The current status string for the message
                required: false
                schema:
                  type: string
              - name: units
                in: query
                description: The number of SMS units used in sending the message
                required: false
                schema:
                  type: string
              - name: callbackref
                in: query
                description: The callbackref value that you passed in your call
                required: false
                schema:
                  type: string
              - name: err
                in: query
                description: Any permanent error encountered in attempting to send the message
                required: false
                schema:
                  type: string
              responses:
                "200":
                  description: Your server returns this code if it accepts the callback
components:
  schemas:
    message:
      required:
      - messageData
      type: object
      properties:
        messageData:
          type: array
          items:
            $ref: "#/components/schemas/messageData"
        styleClass:
          type: string
          description: Pass your ApplicationID
    messageData:
      type: object
      properties:
        messageData:
          type: array
          items:
            required:
            - recipients
            type: object
            properties:
              callbackUrl:
                type: string
                description: Provide URL endpoint to receive status updates and responses
              clientRef:
                type: string
              emailBody:
                type: string
                description: Email body content
              emailReplyToAddress:
                type: string
                description: Email reply to address
              emailSentFromAddress:
                type: string
                description: Email sent from address
              emailSentFromName:
                type: string
                description: Email sent from name
              emailSubject:
                type: string
                description: Email subject
              recipients:
                type: array
                description: List of recipients
                items:
                  $ref: "#/components/schemas/recipient"
              attachments:
                type: array
                description: "Optional list of attachments, only valid "
                items:
                  type: object
                  properties:
                    FileName:
                      type: string
                    FileData:
                      type: string
                      description: Base64 encoded file content
                      format: byte
              sendDateTime:
                type: string
              smsMessage:
                type: string
              DynamicTokens:
                type: object
                properties:
                  $Token1$:
                    type: string
                  $Token2$:
                    type: string
                description: Optional list of dynamic tokens that can be referenced in the message body
              NotificationMessage:
                type: string
                description: Content for Push Notification
                x-stoplight:
                  id: 9x509t0rzoq6g
              XpressionsBody:
                type: string
                description: "Eduspot body for sending specific content to Eduspot, not default SMS/Email"
                x-stoplight:
                  id: frxgyled6243s
      example:
        messageData:
        - callbackUrl: "https://apitesting.xporter.one/TryIt/Callback?sentid={sentid}&clientref={clientref}&recipient={recipient}&status={status}&callbackref={callbackref}&recipientclientid={clientid}&units={units}"
          clientRef: 5E4F539B-E2D1-4178-B31F-244E8E403A9F
          customerId: "1362"
          emailBody: Hey $Token1$! Don't forget to register for the $Token2$! https://tinyurl.com/2p87u29j
          emailSubject: DFE number changes
          password: 424b8416-5656-4b29-bc4c-e46c9f83eea91d08
          recipients:
          - EmailAddress: test@none.existent
          sendXpression: false
          styleClass: TestPartner
          userName: TestPartner
          DynamicTokens:
            $Token1$: Michael
            $Token2$: fundraiser
          attachments:
          - FileName: WordDocument.docx
            FileData: <Base64EncodedFileContent>
    messageResponse:
      type: object
      properties:
        errorMsg:
          type: string
        MessageSentId:
          type: integer
        MessageId:
          type: string
        statusMsg:
          type: string
        transmitDateTime:
          type: string
          format: date-time
        ClientRef:
          type: string
        WarningMessages:
          type: array
          items:
            type: string
    recipient:
      required:
      - ClientId
      - SendTo
      type: object
      properties:
        ClientId:
          type: string
          description: "Unique reference to this particular recipient, used by the callback"
        SendTo:
          maximum: 2
          minimum: 0
          type: integer
          default: 0
        MobileNumber:
          type: string
        IdaasId:
          type: string
          description: "Person identifier obtained from Xporter Data. Can be constructed from consistent prefix per person type and MISID. \n\n|PersonType|Prefix|\n|--|--|\n|Student|PL-|\n|Student Contact|PC-|\n|Staff|PWT-|\n  \n  \n"
        ExternalId:
          type: string
          description: The ID held by the Communications platform imported from its data source. Often the MIS ID but not guaranteed. Prefer to use IdaasId instead
        ContactId:
          type: integer
          description: "The Id for the contact in the Communications platform, obtained from the /Data/Contacts API. If present, overrides IdaasId and ExternalId"
        DynamicTokens:
          type: object
        EmailAddress:
          type: string
          format: email
          x-stoplight:
            id: 3b8m12r6ug1ig
    callback:
      type: string
      description: "GET parameters passed with the CallbackUrl will be populated when we call back to your endpoint\n\nYou can customise the url called by including a `?` in the url and specifying your own parameters, placeholders can be put in your url using `{}` \n\n> **Example:** `www.example.com?source=groupcall&ref={clientref}&studentid={externalid}&message={status}` \n\nIf no `?` is included in the url passed then the url will automatically be appended with our standard response format: \n```\n?sentid={sentid}&contactid={contactid}&externalid={externalid}&clientref={clientref}&recipient={recipient}&status={status}&err={err}&units={units}&callbackref={callbackref}\n```  \n  ### contactid\n  The ID assigned to the recipient by the platform\n  \n  ### externalid\n  The ID known to your platform. This may be the mobile/cell number or the ID from a synced platform, for example a school's SIS.\n  \n  ### clientref\n  Your unique reference for the API call that was made for a specific messageData content\n  \n  ### recipient\n  The mobile/cell that the callback refers to\n  \n  ### status\n  Current status of a given message for a given recipient. You will receive a callback for each status update\n  |Order|Code|Description|Message Status|\n  |---|---|---|---|\n  |1|In Queue|Message received by the API|Processing|\n  |2|Submitted|Message submitted to the aggregator|Processing|\n  |3|Sent|Message sent to the network|Sent|\n  |4|Delivered|Message delivered to the handset|Delivered|\n  |4|Failed|Message failed to send|Failed|\n  |4|Undeliverable|Message reported as unable to deliver to the handset|Failed|\n  \n  The platform will send multiple callbacks, in order. If the message is processed faster than callbacks are sent, only the most recent callback will be made.\n  \n  ### callbackref\n  The unique reference for the recipient\n\n  ### units\n  Number of SMS units used based on message content length. 1 unit = 160 characters\n"
    dynamictoken:
      type: object
      properties:
        $tokenname$:
          type: string
          description: Dynamic property that is the key for your substitution variable. The property name is your token for substitution and the value is the text to insert. Your token must be surrounded by $ eg $TokenName$.
  responses:
    messageResponse:
      description: Standard response object received following POST to the API
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/messageResponse"
          example:
            MessageSentId: 0
            MessageId: 1261.20221107.02517344439098830760-9616fca7b64f405fa9116059403a868f
            statusMsg: In Queue
            transmitDateTime: 2022-11-07T21:34:51.3826134Z
            ClientRef: 5E4F539B-E2D1-4178-B31F-244E8E403A9F
            WarningMessages:
            - null
