openapi: 3.0.0
info:
  title: AuraLine Channel Callback
  description: Set of endpoints that support the communication between a channel and Aura using AuraLine protocol
  version: 1.0.0
tags:
  - name: auraline
    description: Endpoints to send messages to the channel
servers:
  - url: 'http://localhost:8080'
    description: Local server
paths:
  '/auraline/v1/conversations/{conversationId}/activities/{messageId}':
    post:
      tags:
        - auraline
      security:
        - ApiKeyAuth: []
      description: >-
        Send a message from aura to a specific channel
      operationId: postAuralineMessages
      x-router-controller: auraline
      parameters:
        - name: conversationId
          in: path
          description: Identifier of the conversation
          required: true
          schema:
            type: string
        - name: messageId
          in: path
          description: Identifier of the original message
          required: true
          schema:
            type: string
        - name: correlator
          in: header
          description: Cross-system identifier of the request to allow tracing in all systems involved. It is recommended to use UUID.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Activities'
      responses:
        '204':
          description: The operation succeeded. No content was returned.
        '400':
          description: 'The URL, body, or headers in the request are malformed or invalid.'
        '401':
          description: The operation included an invalid or missing Authorization header.
        '403':
          description: You are forbidden from performing this action because your token or secret is invalid.
        '404':
          description: The requested resource was not found.
        '429':
          description: >-
            Too many requests have been submitted to this API. This error may be accompanied by a Retry-After header, which includes the
            suggested retry interval.
        '500':
          description: An internal server error has occurred.
        '502':
          description: The callback service is unavailable or returned an error.
components:
  securitySchemes: {}
  responses: {}
  schemas:
    Activities:
      type: object
      required:
        - activities
      properties:
        activities:
          description: Sorted list of activities containing all the answers generated by the use case.
          type: array
          items:
            $ref: '#/components/schemas/Activity'
    ResourceResponse:
      description: A response containing a resource ID
      type: object
      properties:
        id:
          description: Id of the resource
          type: string
    ChannelAccount:
      description: Channel account information needed to route a message
      type: object
      properties:
        id:
          description: >-
            Channel id for the user or bot on this channel (Example:
            joe@smith.com, or @joesmith or 123456)
          type: string
        name:
          description: Display friendly name
          type: string
        aadObjectId:
          description: This account's object ID within Azure Active Directory (AAD)
          type: string
        role:
          description: 'Role of the entity behind the account (Example: User, Bot, etc.)'
          type: string
    ConversationAccount:
      description: >-
        Conversation account represents the identity of the conversation within
        a channel
      type: object
      properties:
        isGroup:
          description: >-
            Indicates whether the conversation contains more than two
            participants at the time the activity was generated
          type: boolean
        conversationType:
          description: >-
            Indicates the type of the conversation in channels that distinguish
            between conversation types
          type: string
        tenantId:
          description: This conversation's tenant ID
          type: string
        id:
          description: >-
            Channel id for the user or bot on this channel (Example:
            joe@smith.com, or @joesmith or 123456)
          type: string
        name:
          description: Display friendly name
          type: string
        aadObjectId:
          description: This account's object ID within Azure Active Directory (AAD)
          type: string
        role:
          description: 'Role of the entity behind the account (Example: User, Bot, etc.)'
          type: string
    MessageReaction:
      description: Message reaction object
      type: object
      properties:
        type:
          description: Message reaction type
          type: string
    CardAction:
      description: A clickable action
      type: object
      properties:
        type:
          description: The type of action implemented by this button
          type: string
        title:
          description: Text description which appears on the button
          type: string
        image:
          description: 'Image URL which will appear on the button, next to text label'
          type: string
        text:
          description: Text for this action
          type: string
        displayText:
          description: (Optional) text to display in the chat feed if the button is clicked
          type: string
        value:
          description: >-
            Supplementary parameter for action. Content of this property depends
            on the ActionType
          type: object
        channelData:
          type: object
          description: Channel-specific data associated with this action
    SuggestedActions:
      description: SuggestedActions that can be performed
      type: object
      properties:
        to:
          description: >-
            Ids of the recipients that the actions should be shown to.  These
            Ids are relative to the channelId and a subset of all recipients of
            the activity
          type: array
          items:
            type: string
        actions:
          description: Actions that can be shown to the user
          type: array
          items:
            $ref: '#/components/schemas/CardAction'
    Attachment:
      description: An attachment within an activity
      type: object
      properties:
        contentType:
          description: mimetype/Contenttype for the file
          type: string
        contentUrl:
          description: (OPTIONAL) Content Url
          type: string
        content: # any type
          description: (OPTIONAL) Embedded content
        name:
          description: (OPTIONAL) The name of the attachment
          type: string
        thumbnailUrl:
          description: (OPTIONAL) Thumbnail associated with attachment
          type: string
    Entity:
      description: Metadata object pertaining to an activity
      type: object
      properties:
        type:
          description: Type of this entity (RFC 3987 IRI)
          type: string
    ConversationReference:
      description: An object relating to a particular point in a conversation
      type: object
      properties:
        activityId:
          description: (Optional) ID of the activity to refer to
          type: string
        user:
          $ref: '#/components/schemas/ChannelAccount'
        bot:
          $ref: '#/components/schemas/ChannelAccount'
        conversation:
          $ref: '#/components/schemas/ConversationAccount'
        channelId:
          description: Channel ID
          type: string
        serviceUrl:
          description: >-
            Service endpoint where operations concerning the referenced
            conversation may be performed
          type: string
    TextHighlight:
      description: Refers to a substring of content within another field
      type: object
      properties:
        text:
          description: Defines the snippet of text to highlight
          type: string
        occurrence:
          format: int32
          description: >-
            Occurrence of the text field within the referenced text, if multiple
            exist.
          type: integer
    SemanticAction:
      description: Represents a reference to a programmatic action
      type: object
      properties:
        state:
          description: 'State of this action. Allowed values: `start`, `continue`, `done`'
          type: string
        id:
          description: ID of this action
          type: string
        entities:
          description: Entities associated with this action
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Entity'
    Activity:
      description: >-
        An Activity is the basic communication type for the Bot Framework 3.0
        protocol.
      type: object
      required:
        - recipient
      properties:
        type:
          description: Contains the activity type.
          type: string
        id:
          description: Contains an ID that uniquely identifies the activity on the channel.
          type: string
        timestamp:
          format: date-time
          description: >-
            Contains the date and time that the message was sent, in UTC,
            expressed in ISO-8601 format.
          type: string
        localTimestamp:
          format: date-time
          description: "Contains the local date and time of the message, expressed in ISO-8601 format.\r\nFor example, 2016-09-23T13:07:49.4714686-07:00."
          type: string
        localTimezone:
          description: "Contains the name of the local timezone of the message, expressed in IANA Time Zone database format.\r\nFor example, America/Los_Angeles."
          type: string
        serviceUrl:
          description: >-
            Contains the URL that specifies the channel's service endpoint. Set
            by the channel.
          type: string
        channelId:
          description: >-
            Contains an ID that uniquely identifies the channel. Set by the
            channel.
          type: string
        from:
          $ref: '#/components/schemas/ChannelAccount'
        conversation:
          $ref: '#/components/schemas/ConversationAccount'
        recipient:
          $ref: '#/components/schemas/ChannelAccount'
        textFormat:
          description: 'Format of text fields Default:markdown'
          type: string
        attachmentLayout:
          description: 'The layout hint for multiple attachments. Default: list.'
          type: string
        membersAdded:
          description: The collection of members added to the conversation.
          type: array
          items:
            $ref: '#/components/schemas/ChannelAccount'
        membersRemoved:
          description: The collection of members removed from the conversation.
          type: array
          items:
            $ref: '#/components/schemas/ChannelAccount'
        reactionsAdded:
          description: The collection of reactions added to the conversation.
          type: array
          items:
            $ref: '#/components/schemas/MessageReaction'
        reactionsRemoved:
          description: The collection of reactions removed from the conversation.
          type: array
          items:
            $ref: '#/components/schemas/MessageReaction'
        topicName:
          description: The updated topic name of the conversation.
          type: string
        historyDisclosed:
          description: Indicates whether the prior history of the channel is disclosed.
          type: boolean
        locale:
          description: "A locale name for the contents of the text field.\r\nThe locale name is a combination of an ISO 639 two- or three-letter culture code associated with a language\r\nand an ISO 3166 two-letter subculture code associated with a country or region.\r\nThe locale name can also correspond to a valid BCP-47 language tag."
          type: string
        text:
          description: The text content of the message.
          type: string
        speak:
          description: The text to speak.
          type: string
        inputHint:
          description: "Indicates whether your bot is accepting,\r\nexpecting, or ignoring user input after the message is delivered to the client."
          type: string
        summary:
          description: The text to display if the channel cannot render cards.
          type: string
        suggestedActions:
          $ref: '#/components/schemas/SuggestedActions'
        attachments:
          description: Attachments
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        entities:
          description: Represents the entities that were mentioned in the message.
          type: array
          items:
            $ref: '#/components/schemas/Entity'
        channelData:
          $ref: '#/components/schemas/ChannelData'
        action:
          description: >-
            Indicates whether the recipient of a contactRelationUpdate was added
            or removed from the sender's contact list.
          type: string
        replyToId:
          description: Contains the ID of the message to which this message is a reply.
          type: string
        label:
          description: A descriptive label for the activity.
          type: string
        valueType:
          description: The type of the activity's value object.
          type: string
        value:
          description: A value that is associated with the activity.
          type: object
        name:
          description: >-
            The name of the operation associated with an invoke or event
            activity.
          type: string
        relatesTo:
          $ref: '#/components/schemas/ConversationReference'
        code:
          description: >-
            The a code for endOfConversation activities that indicates why the
            conversation ended.
          type: string
        expiration:
          format: date-time
          description: >-
            The time at which the activity should be considered to be "expired"
            and should not be presented to the recipient.
          type: string
        importance:
          description: The importance of the activity.
          type: string
        deliveryMode:
          description: "A delivery hint to signal to the recipient alternate delivery paths for the activity.\r\nThe default delivery mode is \"default\"."
          type: string
        listenFor:
          description: >-
            List of phrases and references that speech and language priming
            systems should listen for
          type: array
          items:
            type: string
        textHighlights:
          description: >-
            The collection of text fragments to highlight when the activity
            contains a ReplyToId value.
          type: array
          items:
            $ref: '#/components/schemas/TextHighlight'
        semanticAction:
          $ref: '#/components/schemas/SemanticAction'
    Suggestion:
      type: object
      properties:
        intent:
          type: string
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityModel'
    Notification:
      type: object
      properties:
        action:
          type: string
          description: This property includes the Aura intention reference informing of the dialog to be executed to accomplish the Telefónica client intent.
        notificationData:
          type: object
          description: This property includes detailed information about the notification being sent to the Telefónica client. The data sent will let Aura predict unusual behaviour in clients billing, balance or data consumption.
    EntityModel:
      type: object
      properties:
        canon:
          type: string
          description: This property includes the canonical form of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.
        endIndex:
          type: integer
          description: The index at which this entity ends in the original user message.
        entity:
          type: string
          description: This property includes the value of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.
        label:
          type: string
          description: This property includes an internally used descriptive tag of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.
        score:
          type: number
          description: This property includes the accuracy (in per 1 units) of the recognized entity sent on behalf of the Telefónica client interacting with the Aura bot instance. In the case of Aura commands this value should be 1 since in this case fully recognized intentions are sent.
        startIndex:
          type: string
          description: The index at which this entity starts in the original user message.
        type:
          type: string
          description: This property includes the type of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.
    dialogContextItem:
          type: object
          description: This property will be sent by the corresponding dialog in any case an extra intention recognition is needed.
          properties:
            text:
              type: string
              description: This property includes the word to be recognized.
            value:
              type: object
              properties:
                intent:
                  type: string
                  description: This property includes the Aura intention reference which will determine the Aura dialog to execute.
                entities:
                  type: array
                  description: This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client.
                  items:
                    $ref: '#/components/schemas/EntityModel'
    AuraCommand:
      type: object
      properties:
        type:
          type: string
          description: This property includes the type of Aura command sent on behalf of the Telefónica client interacting with the Aura bot instance.
          enum:
            - intent
            - suggestion
            - notification
            - operation
            - text
            - event
        value:
          type: object
          oneOf:
            - $ref: '#/components/schemas/Suggestion'
            - $ref: '#/components/schemas/Notification'
        utm:
          type: object
          description: It shows the exact interface element that was used by the user to launch the auraCommand
          properties:
            source:
              type: string
              description: Identifies which site sent the traffic. Please, use the channel name.
            medium:
              type: string
              description: Identifies what type of link was used, such as cost per click or email. In Aura use banner, button, etc.
            campaign:
              type: string
              description: Identifies a specific product promotion or strategic campaign.
            term:
              type: string
              description: Identifies search terms. We still need to define the content of this field.
            content:
              type: string
              description: Identifies what specifically was clicked to bring the user to the site, such as a banner ad or a text link.
        actions:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Action to be performed
              target:
                type: string
                description: Target for the action, such as stb . If the action should be executed by the device used by the user to interact with Aura, the value should be channel . The STB team should consider the value stb and channel indistinctly (in the same way)
              params:
                type: object
                description: An object with the required params for the action.
    ChannelData:
      type: object
      properties:
        intentResult:
          type: object
          properties:
            id:
              type: string
              description: Intent identifier, such as intent.tv.launch. This property should not be used to apply any logic in the channel. To do that it should be used the property name.
            name:
              type: string
              description: Intent name (the intent recognized, processed and resolved by Aura), such as STB_ACTION.PLAY_ON_TV or MEDIA.SEARCH.
            entities:
              type: array
              description: Array of entities detected by Aura (it may be empty)
              items:
                $ref: '#/components/schemas/EntityModel'
        actions:
          type: array
          description: Array of Actions, the actions available for this Aura response
          items:
            type: object
            properties:
              name:
                type: string
                description: Action to be performed
              target:
                type: string
                description: Target for the action, such as stb. If the action should be executed by the device used by the user to interact with Aura, the value should be channel . The STB team should consider the value stb and channel indistinctly (in the same way)
              params:
                type: object
                description: An object with the required params for the action.
              postBack:
                type: object
                description: Specifies the action to be performed by the channel once the action is completed. Depending on the result, independent actions could be executed.
                properties:
                  ok:
                    $ref: '#/components/schemas/AuraCommand'
                  error:
                    $ref: '#/components/schemas/AuraCommand'
        dialogContext:
          type: array
          description: This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client.
          items:
            $ref: '#/components/schemas/dialogContextItem'
        status:
          type: object
          description: Object describing the status of the request sent to the Aura bot instance.
          properties:
            code:
              type: string
              description: Internal Aura status code. We will include a link to a document with the codes in a next release of this document.
            message:
              type: string
              description: Descriptive text with additional information
            params:
              type: object
              description: Extended information about the status, it may be empty or not sent. If exists, it will contain extra params needed to handle programmatically the status properly.
        version:
          type: string
          description: This property encodes the version of the Aura Request-Response Semantic Model being used so the structural dependencies and semantics of the data provided can be properly managed
        correlator:
          type: string
          description: This property contains an UUID uniquely identifying the concrete request sent through the channel. This unique identifier is of great help when doing cross system analysis, as a way to correlate the actions executed by distinct elements of the whole system associated to the fulfilment of the same request
