Jump to

• Request
• Response

Submit a Billing Care Chat Request

post

/invoke/chat

The endpoint submits a Billing Care chat request through the hosted integration route. The /chat endpoint provides an equivalent compatibility alias.

Request

Header Parameters

• X-Session-Id: string
  Specifies the existing session's ID. The response returns the active session's ID in the X-Session-Id header and the response body.

Supported Media Types

• application/json

Request Body - application/json ()

Root Schema : schema

Type: object

Show Source

• account_id: [ "string", "null" ]
  Specifies the optional Billing Care account reference or POID.
• confirmed: boolean
  Default Value: false

  The service accepts this field for compatibility. The API does not support write operations.
• conversation_messages: [ "array", "null" ] conversation_messages
  Specifies the optional legacy conversation history as [role, content] pairs.
• message(required): string
  Minimum Length: 1

  Specifies the customer's billing or payment question.
• operation_payload: [ "object", "null" ] operation_payload
  Additional Properties Allowed: true

  The service accepts this field for compatibility. The API does not support write operations.
• previous_messages: [ "array", "null" ] previous_messages
  Specifies the optional conversation history.
• session_id: [ "string", "null" ]
  Specifies the optional session ID. The X-Session-Id header takes precedence when the request supplies it.
• user_role: string
  Default Value: customer

  The service accepts this field for compatibility.

{
    "type":"object",
    "required":[
        "message"
    ],
    "properties":{
        "message":{
            "type":"string",
            "minLength":1,
            "description":"Specifies the customer's billing or payment question."
        },
        "session_id":{
            "type":[
                "string",
                "null"
            ],
            "description":"Specifies the optional session ID. The X-Session-Id header takes precedence when the request supplies it."
        },
        "account_id":{
            "type":[
                "string",
                "null"
            ],
            "description":"Specifies the optional Billing Care account reference or POID."
        },
        "previous_messages":{
            "type":[
                "array",
                "null"
            ],
            "description":"Specifies the optional conversation history.",
            "items":{
                "$ref":"#/components/schemas/PreviousMessage"
            }
        },
        "conversation_messages":{
            "type":[
                "array",
                "null"
            ],
            "description":"Specifies the optional legacy conversation history as [role, content] pairs.",
            "items":{
                "type":"array",
                "minItems":2,
                "maxItems":2,
                "prefixItems":[
                    {
                        "type":"string"
                    },
                    {
                        "type":"string"
                    }
                ]
            }
        },
        "operation_payload":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"The service accepts this field for compatibility. The API does not support write operations."
        },
        "confirmed":{
            "type":"boolean",
            "default":false,
            "description":"The service accepts this field for compatibility. The API does not support write operations."
        },
        "user_role":{
            "type":"string",
            "default":"customer",
            "description":"The service accepts this field for compatibility."
        }
    }
}

Nested Schema : conversation_messages

Type: array

Specifies the optional legacy conversation history as [role, content] pairs.

Show Source

• Array of: array items
  Minimum Number of Items: 2

  Maximum Number of Items: 2

{
    "type":[
        "array",
        "null"
    ],
    "description":"Specifies the optional legacy conversation history as [role, content] pairs.",
    "items":{
        "type":"array",
        "minItems":2,
        "maxItems":2,
        "prefixItems":[
            {
                "type":"string"
            },
            {
                "type":"string"
            }
        ]
    }
}

Nested Schema : operation_payload

Type: object

Additional Properties Allowed: true

The service accepts this field for compatibility. The API does not support write operations.

Nested Schema : previous_messages

Type: array

Specifies the optional conversation history.

Show Source

• Array of: object PreviousMessage

{
    "type":[
        "array",
        "null"
    ],
    "description":"Specifies the optional conversation history.",
    "items":{
        "$ref":"#/components/schemas/PreviousMessage"
    }
}

Nested Schema : items

Type: array

Minimum Number of Items: 2

Maximum Number of Items: 2

Nested Schema : PreviousMessage

Type: object

Show Source

• content(required): string
  Minimum Length: 1

  Example: What was my previous bill?
• role(required): string
  Minimum Length: 1

  Example: user

{
    "type":"object",
    "required":[
        "role",
        "content"
    ],
    "properties":{
        "role":{
            "type":"string",
            "minLength":1,
            "example":"user"
        },
        "content":{
            "type":"string",
            "minLength":1,
            "example":"What was my previous bill?"
        }
    }
}

Security

• bearerAuth: http
  Type: http

  Description: The deployment requires bearer authentication only when it enables IDCS authentication.

Back to Top

Response

200 Response

The request was completed successfully. If the system throws a runtime error, the response code 200 is returned alongside the error message in the response body. If a request asks for another account's bill details, the response body contains status: error instead of an HTTP error response.

Headers

• X-Session-Id:
  Specifies the active conversation's session ID.

Body ()

Root Schema : ChatResponse

Type: object

Show Source

• account_id: string
  Specifies the account's display ID when the service resolves an account.
• agent: string
  Example: billing_care_agent
• follow_up_questions: array follow_up_questions
• intent: string
  Specifies the intent that the service returns in certain validation responses.
• requested_account_id: string
  Specifies the account reference that the service uses to process the request.
• response_format: string
  Allowed Values: [ "string", "list", "table" ]
• response_text(required): string
  Specifies the customer-facing answer, which always ends with the AI-generated-response disclosure.
• session_id(required): string
• status(required): string
  Allowed Values: [ "ok", "error" ]

{
    "type":"object",
    "required":[
        "status",
        "response_text",
        "session_id"
    ],
    "properties":{
        "status":{
            "type":"string",
            "enum":[
                "ok",
                "error"
            ]
        },
        "agent":{
            "type":"string",
            "example":"billing_care_agent"
        },
        "intent":{
            "type":"string",
            "description":"Specifies the intent that the service returns in certain validation responses."
        },
        "response_format":{
            "type":"string",
            "enum":[
                "string",
                "list",
                "table"
            ]
        },
        "response_text":{
            "type":"string",
            "description":"Specifies the customer-facing answer, which always ends with the AI-generated-response disclosure."
        },
        "follow_up_questions":{
            "type":"array",
            "items":{
                "type":"string"
            }
        },
        "account_id":{
            "type":"string",
            "description":"Specifies the account's display ID when the service resolves an account."
        },
        "requested_account_id":{
            "type":"string",
            "description":"Specifies the account reference that the service uses to process the request."
        },
        "session_id":{
            "type":"string"
        }
    }
}

Nested Schema : follow_up_questions

Type: array

Show Source

• Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    }
}

Examples

Select an example Successful Bill Response Bill Details Requested for Another Account

401 Response

The request does not include a valid bearer token, which the deployment requires when IDCS authentication is enabled.

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• detail(required): string

{
    "type":"object",
    "required":[
        "detail"
    ],
    "properties":{
        "detail":{
            "type":"string"
        }
    }
}

422 Response

The request contains an invalid body or header.

Body ()

Root Schema : ValidationErrorResponse

Type: object

Show Source

• detail(required): array detail

{
    "type":"object",
    "required":[
        "detail"
    ],
    "properties":{
        "detail":{
            "type":"array",
            "items":{
                "type":"object",
                "required":[
                    "loc",
                    "msg",
                    "type"
                ],
                "properties":{
                    "loc":{
                        "type":"array",
                        "items":{
                            "oneOf":[
                                {
                                    "type":"string"
                                },
                                {
                                    "type":"integer"
                                }
                            ]
                        }
                    },
                    "msg":{
                        "type":"string"
                    },
                    "type":{
                        "type":"string"
                    }
                }
            }
        }
    }
}

Nested Schema : detail

Type: array

Show Source

• Array of: object items

{
    "type":"array",
    "items":{
        "type":"object",
        "required":[
            "loc",
            "msg",
            "type"
        ],
        "properties":{
            "loc":{
                "type":"array",
                "items":{
                    "oneOf":[
                        {
                            "type":"string"
                        },
                        {
                            "type":"integer"
                        }
                    ]
                }
            },
            "msg":{
                "type":"string"
            },
            "type":{
                "type":"string"
            }
        }
    }
}

Nested Schema : items

Type: object

Show Source

• loc(required): array loc
• msg(required): string
• type(required): string

{
    "type":"object",
    "required":[
        "loc",
        "msg",
        "type"
    ],
    "properties":{
        "loc":{
            "type":"array",
            "items":{
                "oneOf":[
                    {
                        "type":"string"
                    },
                    {
                        "type":"integer"
                    }
                ]
            }
        },
        "msg":{
            "type":"string"
        },
        "type":{
            "type":"string"
        }
    }
}

Nested Schema : loc

Type: array

Show Source

• Array of: items

{
    "type":"array",
    "items":{
        "oneOf":[
            {
                "type":"string"
            },
            {
                "type":"integer"
            }
        ]
    }
}

Nested Schema : items

Match One Schema

Show Source

• string
• integer

{
    "oneOf":[
        {
            "type":"string"
        },
        {
            "type":"integer"
        }
    ]
}

502 Response

The billing agent could not process the request.

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• detail(required): string

{
    "type":"object",
    "required":[
        "detail"
    ],
    "properties":{
        "detail":{
            "type":"string"
        }
    }
}

503 Response

The billing agent is temporarily unavailable.

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• detail(required): string

{
    "type":"object",
    "required":[
        "detail"
    ],
    "properties":{
        "detail":{
            "type":"string"
        }
    }
}

Back to Top