{
  "openapi": "3.0.1",
  "info": {
    "title": "Flow",
    "description": "This API documentation is in support of the public-facing API for the Flow solution. Production API endpoints will be supplied.",
    "version": "1.1.0"
  },
  "servers": [
    {
      "url": "https://flow-callback.clickatell.com/",
      "description": "Production server"
    },
    {
      "url": "https://control-callback-uat.payd.co/",
      "description": "Sandbox/UAT server"
    }
  ],
  "paths": {
    "/callback": {
      "post": {
        "tags": [
          "External Link Callback"
        ],
        "summary": "Direct an end-user to an external web page",
        "description": "The External Link Handler API allows you to direct an end-user to an external web page from within a Flow conversation and then return to the Flow conversation with optional additional data gathered from the external web page.<br /><br/>The end-user can then continue with the conversational workflow according to the steps defined in Flow.",
        "parameters": [
          {
            "name": "reference",
            "in": "header",
            "description": "A reference to be passed as a header. This value is also required in the body section, please refer accordingly for the description.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Payload describing the external link",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Externallink"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successfully validated the response and returned data appended to matched session.",
            "content": {}
          },
          "400": {
            "description": "A bad/invalid reference was returned and the session could not be matched",
            "content": {}
          }
        }
      }
    },
    "/chat/callback": {
      "post": {
        "tags": [
          "Wait for Callback"
        ],
        "summary": "Wait for an external system to initiate a callback",
        "description": "The Wait for Callback node was created to facilitate an asynchronous process external to Chat Flow. For example waiting for an external client system to generate an invoice.<br /><br />This node will block the flow until a callback was received or the timed out was reached. The timeout is 1 minute less that the session length.<br/> <br />This node should be used in conjunction with the Set Variable Node to first set a UUID as a variable and then use that UUID in the Reference Field on the node and in the Callback API so that the Callback Handler can identify that the callback belong to a specific session.<br /><br/>Once the callback is received the end-user can then continue with the conversational workflow according to the steps defined in Flow.",
        "parameters": [
          {
            "name": "reference",
            "in": "header",
            "description": "A reference to be passed as a header.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Payload describing the callback result",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Waitforcallback"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Successfully validated the response and returned data appended to matched session."
          },
          "204": {
            "description": "Callback has previously been processed in is being ignored."
          },
          "400": {
            "description": "A bad/invalid reference was returned and the session could not be matched, or the session has expired."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Externallink": {
        "required": [
          "result"
        ],
        "type": "object",
        "properties": {
          "result": {
            "type": "string",
            "description": "Used to evaluate success or failure in Flow and can be any value you wish to return for evaluation",
            "example": "success"
          },
          "reference": {
            "type": "string",
            "description": "A unique hash generated by Flow based on SessionID and SourceID that allows us to identify the user's session. This value is automatically appended as a query parameter on external links and should be intercepted and returned with the callback for validation (in header and body): e.g. `https://www.example.com?reference=f7_4hn5=8f&%#nK=`"
          },
          "data": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "An optional hashmap with any key and value that can be referenced in the flow later on.",
            "example": {
              "invoice": 123456,
              "amount": 100
            }
          }
        }
      },
      "Waitforcallback": {
        "type": "object",
        "example": {
          "body": {
            "read": 100
          },
          "result": {
            "ben": 10
          }
        }
      }
    }
  }
}