openapi: 3.0.3
info:
  title: Messenger API
  description: "# Introduction \n\n  Groupcall Messenger provides a REST-based API for sending text messages and emails via Messenger including recording of messages in the Messenger history screens and, where applicable, charging specific schools for the messages sent on their behalf.\n  \n# Authentication\n\n  The SendMessage API functions has 2 forms of authentication. \n  \n  Passing an API key and the Customer ID for the specific organisations (Both provided by Groupcall) – These are issued on a per customer basis to the integrator\n  \n  Passing an API key and the Customer ID for the Partner (Both provided by Groupcall) – This is issued one set per partner and is used for all API use by the partner. \n  \n  \n\n# Testing and Development \n\n  Groupcall make available a parallel Messenger environment at https://apitesting.groupcall.com/. This is fully isolated from the Messenger production environment.\n\n\nWhen a new partner is integrating with Groupcall Messenger we make available a sandbox account on this testing environment for you to develop against the SendMessage API and use the Messenger History page via the UI to view your successes (and failures!).  Once you are happy that your integration is ready we can enable transmission of SMS and Email to complete final API testing. \n# Common Principles\n## Recipients\n    \nThe Messenger API is designed to support delegated messages, which in the context of a school would mean:\nInclude the ID of the Student > Send message to Student’s Parent that is held in the Messenger data store\nYou can modify the behaviour of this functionality with the SendTo property:\n\n  |SendTo Value|Description|\n  |------------|-----------|\n  |0|Send directly to defined recipient|\n  |1|Send to Priority contact of defined recipient|\n  |2|Send to All contacts of defined recipient|\n\n\n\n## Status Callbacks\nPass a URL to receive status updates on the messages that you send. If no parameters are provided, we will include all options in the GET parameters when we call you back.\n\nCustomise your callback by including only documented parameters you need in your constructed URL to receive dynamic updates.\n\nYou can use our callback testing site to visualise callbacks before implementing your own endpoint. It does require 2 additional parameters beyond what is normally needed: * id - unique reference for your callback * estab - reference for the customer\n> https://apitesting.xporter.one/Tryit/Callback\n## Batching\nTo reduce the number of times you need to call the API to send lots of messages, it is possible to send messages in batches.\nMultiple recipients can be included for the same message and have personalised content included by populating the optional `DynamicTokens` object.\n### Dynamic Tokens\n  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$.\n\n\nWe recommend a maximum of 100 recipients per message. This may mean that you need to generate multiple messages depending on the size of your recipient list for a given message.\n\n## Units vs Messages\nA single SMS unit is 160 characters long. A message may be comprised of multiple units. Units are the chargeable item, so a message of 200 characters would be charged as 2 SMS units.\n* Unit Length: 160 Characters\n* Maximum Units per Message: 10 Units\n\n### SMS message length and Unicode\nOverview SMS messages are constructed in sections, referred to as segments. Message sends are costed and charged per segment. In most geographical locations around the world, a single SMS segment represents a maximum of 160 standard GSM characters. Spaces between words are also counted as characters. When typing your message, be aware that the longer it gets, the more it costs.\n#### Long SMS messages\nSMS messages containing more than 160 standard GSM characters are known as long messages. Smartphone handsets can combine or stitch multiple SMS segments into a single message. This is a concatenated message. \nWhen segments are stitched together, seven characters are sacrificed per segment to help with concatenation. Therefore, the maximum character count for long messages are:\n* 2 message segments: 153+153=306 standard GSM characters\n* 3 message segments: 153+153+153=459 standard GSM characters\n* 4 message segments: 153+153+153+153=612 standard GSM characters\n\n#### Standard GSM character set\nThe standard GSM set contains the most widely used characters in everyday language: all Latin characters (A-Z), digits (0-9), plus a few special characters such as Ö and è. For each standard GSM character typed into a message, a single character space is consumed from the SMS segment.\n#### Extended GSM character set\nIn addition to standard GSM characters, certain characters from the extended GSM character set, such as € and { symbols, can be used in SMS messages. The 160 segment count remains, however these characters use additional space; x2 spaces per character to be exact.\n#### Unicode (non-standard GSM)\nNon-standard GSM characters are referred to as Unicode characters. Unicode provides a set of additional characters, including punctuation marks, mathematical symbols, technical symbols, arrows, and characters making up non-Latin alphabets, such as Thai, Chinese, or Arabic script and Emojis.\nWhile Unicode is supported in SMS messaging, be aware that its usage affects your message length.\nIntroducing a single Unicode character in your message content changes the character encoding to Unicode (UCS-2) and immediately reduces the segment character limit from 160 to 70 characters for a single message.\nWhen messages are stitched together with Unicode characters included, three characters are sacrificed per segment. Therefore:\n* 2 message segments with Unicode: 67+67=134 characters\n* 3 message segments with Unicode: 67+67+67=201 characters\n* 4 message segments with Unicode: 67+67+67+67=268 characters\n#### Using Emoji in your SMS messages\nEmoji use is supported in SMS messaging. All Emojis are treated as Unicode characters, reducing message segments to 70 characters. Older 16-bit Emojis count as a single character count and newer 32-bit emojis count as two characters in a message.\n    \n# SMS Delivery & Numbers\nSMS messages can be delivered internationally and as such mobile/cell numbers must be provided to the API with their international country code prepended to the number.\n## US SMS Delivery\n**Toll Free Numbers** These numbers can only be used to deliver within the United States (Region code 1)\nTo send outside of the United States you will need to specify an alphanumeric sender ID by adding `SMSSender` as an additional property to the `messageData` object."
  contact:
    email: support@groupcall.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 3.1.0
servers:
- url: https://virtserver.swaggerhub.com/CBUK/Messenger/1.0.0
  description: Mock API
- 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)
tags:
- name: SendMessage_V3 Delivery APIs
  description: APIs for sending messages via different routes
- name: SendMessage_V3 Opt In APIs
  description: Get and set opt in/out values for receipients
- name: SendMessage_V3 Usage APIs
  description: Retrieve usage data for customer accounts
paths:
  /api/SendMessage_V3/SMS:
    post:
      tags:
      - SendMessage_V3 Delivery APIs
      summary: Send SMS
      description: "This method allows you to batch up multiple SMS messages to be sent to multiple recipients, and optionally to specify a Callback URL for status updates on a per-message per-recipient basis. "
      operationId: SendSMSMessage
      requestBody:
        description: |
          Example POST body content for sending a single SMS to a single recipient
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/messageDataSMS"
            example:
              messageData:
              - ClientRef: 5E4F539B-E2D1-4178-B31F-244E8E403A9F
                UserName: TestPartner
                CustomerId: 1362
                Password: 424b8416-5656-4b29-bc4c-e46c9f83eea91d08
                SMSMessage: Hey $Token1$! Don't forget to register for the $Token2$! https://tinyurl.com/2p87u29j
                CallbackUrl: "https://apitesting.xporter.one/TryIt/Callback?sentid={sentid}&clientref={clientref}&recipient={recipient}&status={status}&callbackref={callbackref}&recipientclientid={clientid}&units={units}"
                Recipients:
                - ClientId: 885C45FD-552B-4F19-A354-3CC4920E48D6
                  SendTo: 0
                  MobileNumber: "44700000000"
                  DynamicTokens:
                    $Token1$: Michael
                    $Token2$: fundraiser
              styleClass: TestPartner
      responses:
        "200":
          $ref: "#/components/responses/messageResponse"
        "400":
          description: "invalid input, object invalid"
      callbacks:
        messageResponse:
          '{$request.body#/messageData/[0]/CallbackUrl}':
            get:
              summary: Message status callback request to CallbackUrl
              parameters:
              - name: id
                in: query
                description: Your unique ID reference
                required: false
                schema:
                  type: string
              - name: sentid
                in: query
                description: The Messenger internal id for this specific message
                required: false
                schema:
                  type: string
              - name: contactid
                in: query
                description: The Messenger 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 contact
                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
  /api/SendMessage_V3/Email:
    post:
      tags:
      - SendMessage_V3 Delivery APIs
      summary: Send Email
      description: "This method allows you to batch up multiple Email messages to be sent to multiple recipients, and optionally to specify a Callback URL for status updates on a per-message per-recipient basis. "
      operationId: SendEmailMessage
      requestBody:
        description: |
          Example POST body content for sending a single SMS to a single recipient
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/messageDataEmail"
      responses:
        "200":
          $ref: "#/components/responses/messageResponse"
        "400":
          description: "invalid input, object invalid"
      callbacks:
        messageResponse:
          '{$request.body#/messageData/[0]/CallbackUrl}':
            get:
              summary: Message status callback request to CallbackUrl
              parameters:
              - name: id
                in: query
                description: Your unique ID reference
                required: false
                schema:
                  type: string
              - name: sentid
                in: query
                description: The Messenger internal id for this specific message
                required: false
                schema:
                  type: string
              - name: contactid
                in: query
                description: The Messenger 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 contact
                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
  /api/SendMessage_V3/PartnerRoute:
    post:
      tags:
      - SendMessage_V3 Delivery APIs
      summary: Send Multi Content
      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* Xpressions\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 Messenger 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. It can also be constructed with a  consistent 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: sendMultiContent
      requestBody:
        description: Send Message
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/messageDataMulti"
            example:
              PartnerKey: 0caad7cf-ad6f-4580-add2-6d941c86f683
              messageData:
              - ClientRef: 5E4F539B-E2D1-4178-B31F-244E8E403A9F
                UserName: TestPartner
                CustomerId: 1362
                Password: 424b8416-5656-4b29-bc4c-e96c9f43eea91d08
                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
                SendDateTime: 2017-05-30T09:48:58.3608097+00:00
                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 Messenger internal id for this specific message
                required: false
                schema:
                  type: string
              - name: contactid
                in: query
                description: The Messenger 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
  /api/SendMessage_V3/OptIn:
    post:
      tags:
      - SendMessage_V3 Opt In APIs
      summary: (Documentation in Progress) Set or update Opt In status for a recipient / number combination
      description: This method allows you to update or set the Opt In status for a recipient and a given incoming number
      operationId: optIn
      requestBody:
        description: POST body content to set Opt In / Out status for a recipient
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/optInPayload"
            example:
              CustomerId: 1362
              Password: 424b8416-5656-4b29-bc4c-e46c9f83eea91d08
              ShortCode: "110002233213"
              RecipientNumber: "18973434298"
              Keyword: STOP
      responses:
        "200":
          $ref: "#/components/responses/optInResponse"
        "400":
          description: "invalid input, object invalid"
  /api/SendMessage_V3/OptInBulk:
    post:
      tags:
      - SendMessage_V3 Opt In APIs
      summary: (Documentation in Progress) Set or update Opt In status for a collection of recipients / numbers combinations
      description: This method allows you to update or set the Opt In status for a collection of recipients for a given incoming number
      operationId: optInBulk
      responses:
        "200":
          $ref: "#/components/responses/messageResponse"
        "400":
          description: "invalid input, object invalid"
  /api/SendMessage_V3/fetchOptInStatus:
    post:
      tags:
      - SendMessage_V3 Opt In APIs
      summary: (Documentation in Progress) Fetch the Opt In status of a recipient / number
      description: This method allows you to fetch the current Opt In status of a recipient for a given incoming number
      operationId: fetchOptInStatus
      responses:
        "200":
          $ref: "#/components/responses/messageResponse"
        "400":
          description: "invalid input, object invalid"
  /api/SendMessage_V3/GetUsageData:
    post:
      tags:
      - SendMessage_V3 Usage APIs
      summary: (Documentation in Progress) Fetch the usage data for a specified customer
      description: This method allows you to fetch the usage data for a specified customer within a date range
      operationId: getUsageData
      responses:
        "200":
          $ref: "#/components/responses/messageResponse"
        "400":
          description: "invalid input, object invalid"
components:
  schemas:
    message:
      required:
      - messageData
      type: object
      properties:
        messageData:
          type: array
          items:
            $ref: "#/components/schemas/messageDataSMS"
        styleClass:
          type: string
          description: Pass your ApplicationID
    messageDataSMS:
      required:
      - CustomerId
      - Password
      - Recipients
      - SMSMessage
      - UserName
      - styleClass
      type: object
      properties:
        UserName:
          type: string
          description: "Your ApplicationID, provided by Groupcall"
        CustomerId:
          type: string
          description: "Unique Customer Id, provided by Groupcall"
        Password:
          type: string
          description: "Unique API key per customer, provided by Groupcall"
        SMSMessage:
          type: string
          description: Content of SMS Message
        CallbackUrl:
          type: string
          description: Provide URL endpoint to receive status updates and responses
        SendDateTime:
          type: string
          description: "Optionally send date in UTC if planning to send in future, else leave null"
        SMSSender:
          type: string
          description: Alpha numeric string of length 3 to 11 characters. Required when delivering messages internationally (outside of United States)
        Recipients:
          type: array
          items:
            $ref: "#/components/schemas/recipientSMS"
    messageDataEmail:
      type: object
      properties:
        messageData:
          type: array
          items:
            required:
            - customerId
            - emailBody
            - password
            - recipients
            - styleClass
            type: object
            properties:
              callbackUrl:
                type: string
                description: Provide URL endpoint to receive status updates and responses
              clientRef:
                type: string
              customerId:
                type: string
                description: "Your ApplicationID, provided by Groupcall"
              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
              password:
                type: string
                description: "Unique API key per customer, provided by Groupcall"
              recipients:
                type: array
                description: List of recipients
                items:
                  required:
                  - EmailAddress
                  type: object
                  properties:
                    EmailAddress:
                      type: string
                      description: Recipient email address
              attachments:
                type: array
                description: Optional list of attachments
                items:
                  type: object
                  properties:
                    FileName:
                      type: string
                    FileData:
                      type: string
                      description: Base64 encoded file content
                      format: byte
              sendDateTime:
                type: string
              styleClass:
                type: string
                description: "Style class TODO: Expand description"
              userName:
                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
      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>
    messageDataMulti:
      type: object
      properties:
        messageData:
          type: array
          items:
            required:
            - customerId
            - emailBody
            - password
            - recipients
            type: object
            properties:
              callbackUrl:
                type: string
                description: Provide URL endpoint to receive status updates and responses
              clientRef:
                type: string
              customerId:
                type: string
                description: "Your ApplicationID, provided by Groupcall"
              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
              password:
                type: string
                description: "Unique API key per customer, provided by Groupcall"
              recipients:
                type: array
                description: List of recipients
                items:
                  $ref: "#/components/schemas/recipientMulti"
              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
              sendXpression:
                type: boolean
              smsMessage:
                type: string
              styleClass:
                type: string
              userName:
                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: "Xpressions body for sending specific content to Xpression, 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
    recipientSMS:
      required:
      - ClientId
      - MobileNumber
      - 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. 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 messenger 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 Messenger platform, obtained from the /Data/Contacts API. If present, overrides IdaasId and ExternalId"
        DynamicTokens:
          type: array
          items:
            $ref: "#/components/schemas/dynamictoken"
    recipientMulti:
      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. 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 messenger 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 Messenger 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$.
    optInPayload:
      required:
      - CustomerId
      - Keyword
      - Password
      - RecipientNumber
      - ShortCode
      type: object
      properties:
        CustomerId:
          type: string
          description: "Unique Customer Id, provided by Groupcall"
        Password:
          type: string
          description: "Unique API key per customer, provided by Groupcall"
        ShortCode:
          type: string
          description: Pass your ApplicationID
        RecipientNumber:
          type: string
          description: Mobile / cell number of the individual
        Keyword:
          type: string
          description: SMS Keyword to apply to this recipient eg STOP
        SchoolName:
          type: string
          description: Pass your ApplicationID
        RecipientName:
          type: string
          description: Pass your ApplicationID
    optInResponse:
      type: object
      properties:
        ShortCode:
          type: string
          description: Pass your ApplicationID
        RecipientNumber:
          type: string
          description: Mobile / cell number of the individual
        IsOptedIn:
          type: integer
          description: Pass your ApplicationID
        Message:
          type: string
          description: Mobile / cell number of the individual
  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
    optInResponse:
      description: Standard response object received following POST to the API
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/optInResponse"
          example:
            ShortCode: "110002233213"
            RecipientNumber: "18973434298"
            IsOptedIn: 0
            Message: ""
