Skip to main content

epilot Chat API

Usage​

import { epilot } from '@epilot/sdk'

epilot.authorize(() => '<token>')
const { data } = await epilot.chat.listWebsiteChats(...)

Tree-shakeable import​

import { getClient, authorize } from '@epilot/sdk/chat'

const chatClient = getClient()
authorize(chatClient, () => '<token>')
const { data } = await chatClient.listWebsiteChats(...)

Operations​

Website Chats

Other

Schemas

listWebsiteChats​

GET /v1/website-chats

const { data } = await client.listWebsiteChats({
  cursor: 'example',
})
Response
{
  "website_chats": [
    {
      "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "settings": {
        "allowed_origins": ["string"],
        "default_locale": "en",
        "design_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "authentication": {
          "email_code": {
            "email_template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          },
          "portal": {
            "portal_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          }
        },
        "self_service": {
          "actions": [
            {
              "action": "submit_meter_reading",
              "enabled": true,
              "fulfilment": "in_chat",
              "journey_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "url": "string",
              "access": "anonymous",
              "guidance": "string"
            }
          ]
        }
      },
      "website_chat_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "org_id": "string",
      "binding_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z",
      "embed": {
        "script_url": "https://example.com/path",
        "chat_api_origin": "https://example.com/path",
        "demo_url": "https://example.com/path"
      }
    }
  ],
  "next_cursor": "string"
}

createWebsiteChat​

POST /v1/website-chats

const { data } = await client.createWebsiteChat(
  null,
  {
    agent_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    settings: {
      allowed_origins: ['string'],
      default_locale: 'en',
      design_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
      authentication: {
        email_code: {
          email_template_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
        },
        portal: {
          portal_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
        }
      },
      self_service: {
        actions: [
          {
            action: 'submit_meter_reading',
            enabled: true,
            fulfilment: 'in_chat',
            journey_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
            url: 'string',
            access: 'anonymous',
            guidance: 'string'
          }
        ]
      }
    }
  },
)
Response
{
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "settings": {
    "allowed_origins": ["string"],
    "default_locale": "en",
    "design_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "authentication": {
      "email_code": {
        "email_template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      },
      "portal": {
        "portal_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    },
    "self_service": {
      "actions": [
        {
          "action": "submit_meter_reading",
          "enabled": true,
          "fulfilment": "in_chat",
          "journey_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "url": "string",
          "access": "anonymous",
          "guidance": "string"
        }
      ]
    }
  },
  "website_chat_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "org_id": "string",
  "binding_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "embed": {
    "script_url": "https://example.com/path",
    "chat_api_origin": "https://example.com/path",
    "demo_url": "https://example.com/path"
  }
}

getWebsiteChat​

GET /v1/website-chats/{website_chat_id}

const { data } = await client.getWebsiteChat({
  website_chat_id: 'example',
})
Response
{
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "settings": {
    "allowed_origins": ["string"],
    "default_locale": "en",
    "design_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "authentication": {
      "email_code": {
        "email_template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      },
      "portal": {
        "portal_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    },
    "self_service": {
      "actions": [
        {
          "action": "submit_meter_reading",
          "enabled": true,
          "fulfilment": "in_chat",
          "journey_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "url": "string",
          "access": "anonymous",
          "guidance": "string"
        }
      ]
    }
  },
  "website_chat_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "org_id": "string",
  "binding_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "embed": {
    "script_url": "https://example.com/path",
    "chat_api_origin": "https://example.com/path",
    "demo_url": "https://example.com/path"
  }
}

updateWebsiteChat​

PUT /v1/website-chats/{website_chat_id}

const { data } = await client.updateWebsiteChat(
  {
    website_chat_id: 'example',
  },
  {
    agent_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    settings: {
      allowed_origins: ['string'],
      default_locale: 'en',
      design_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
      authentication: {
        email_code: {
          email_template_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
        },
        portal: {
          portal_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
        }
      },
      self_service: {
        actions: [
          {
            action: 'submit_meter_reading',
            enabled: true,
            fulfilment: 'in_chat',
            journey_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
            url: 'string',
            access: 'anonymous',
            guidance: 'string'
          }
        ]
      }
    },
    version: 1
  },
)
Response
{
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "settings": {
    "allowed_origins": ["string"],
    "default_locale": "en",
    "design_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "authentication": {
      "email_code": {
        "email_template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      },
      "portal": {
        "portal_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    },
    "self_service": {
      "actions": [
        {
          "action": "submit_meter_reading",
          "enabled": true,
          "fulfilment": "in_chat",
          "journey_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "url": "string",
          "access": "anonymous",
          "guidance": "string"
        }
      ]
    }
  },
  "website_chat_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "org_id": "string",
  "binding_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "embed": {
    "script_url": "https://example.com/path",
    "chat_api_origin": "https://example.com/path",
    "demo_url": "https://example.com/path"
  }
}

deleteWebsiteChat​

DELETE /v1/website-chats/{website_chat_id}

const { data } = await client.deleteWebsiteChat({
  website_chat_id: 'example',
  version: 1,
})

createWebsiteChatPreviewGrant​

POST /v1/website-chats/{website_chat_id}/preview-grant

const { data } = await client.createWebsiteChatPreviewGrant(
  {
    website_chat_id: 'example',
  },
  {
    design_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    demo_customer: false
  },
)
Response
{
  "grant": "string",
  "expires_in": 0,
  "frame_origin": "https://example.com/path",
  "website_chat": {
    "key": "string",
    "assistant_name": {
      "de": "string",
      "en": "string"
    },
    "greeting": {
      "de": "string",
      "en": "string"
    },
    "defaultLocale": "en",
    "login_methods": ["email_code"],
    "starters": {
      "de": ["string"],
      "en": ["string"]
    },
    "actions": {
      "meter_reading": true,
      "meter_reading_journey_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "design": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "last_modified_at": "string",
      "style": {
        "palette": {
          "primary": "string",
          "background": "string"
        },
        "typography": {
          "font": {
            "font_family": "string"
          }
        },
        "shape": {
          "border_radius": 0
        }
      },
      "spark_theme": {
        "accentColor": "string",
        "backgroundColor": "string",
        "fontBody": "string",
        "fontHeading": "string",
        "radius": "string",
        "scaling": "string",
        "spacing": "string",
        "appearance": "string",
        "neutralColor": "string",
        "styleVariant": "string",
        "labelPosition": "string",
        "inputStyle": "string",
        "inputColor": "string",
        "cardVariant": "string",
        "cardColor": "string",
        "highContrast": true
      }
    },
    "locales": ["en"]
  }
}

getPublicWebsiteChat​

GET /v1/website-chats/{website_chat_id}/configuration

const { data } = await client.getPublicWebsiteChat({
  website_chat_id: 'example',
})
Response
{
  "key": "string",
  "assistant_name": {
    "de": "string",
    "en": "string"
  },
  "greeting": {
    "de": "string",
    "en": "string"
  },
  "defaultLocale": "en",
  "login_methods": ["email_code"],
  "starters": {
    "de": ["string"],
    "en": ["string"]
  },
  "actions": {
    "meter_reading": true,
    "meter_reading_journey_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "design": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "last_modified_at": "string",
    "style": {
      "palette": {
        "primary": "string",
        "background": "string"
      },
      "typography": {
        "font": {
          "font_family": "string"
        }
      },
      "shape": {
        "border_radius": 0
      }
    },
    "spark_theme": {
      "accentColor": "string",
      "backgroundColor": "string",
      "fontBody": "string",
      "fontHeading": "string",
      "radius": "string",
      "scaling": "string",
      "spacing": "string",
      "appearance": "string",
      "neutralColor": "string",
      "styleVariant": "string",
      "labelPosition": "string",
      "inputStyle": "string",
      "inputColor": "string",
      "cardVariant": "string",
      "cardColor": "string",
      "highContrast": true
    }
  },
  "locales": ["en"]
}

createPublicChatGrant​

POST /v1/bootstrap

const { data } = await client.createPublicChatGrant(
  null,
  {
    website_chat_id: 'string'
  },
)
Response
{
  "grant": "string",
  "expires_in": 60,
  "frame_origin": "https://example.com/path"
}

createAnonymousChatSession​

POST /v1/sessions

const { data } = await client.createAnonymousChatSession(
  null,
  {
    grant: 'string'
  },
)
Response
{
  "token": "string",
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "expires_at": 0,
  "website_chat": {
    "key": "string",
    "assistant_name": {
      "de": "string",
      "en": "string"
    },
    "greeting": {
      "de": "string",
      "en": "string"
    },
    "defaultLocale": "en",
    "login_methods": ["email_code"],
    "starters": {
      "de": ["string"],
      "en": ["string"]
    },
    "actions": {
      "meter_reading": true,
      "meter_reading_journey_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "design": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "last_modified_at": "string",
      "style": {
        "palette": {
          "primary": "string",
          "background": "string"
        },
        "typography": {
          "font": {
            "font_family": "string"
          }
        },
        "shape": {
          "border_radius": 0
        }
      },
      "spark_theme": {
        "accentColor": "string",
        "backgroundColor": "string",
        "fontBody": "string",
        "fontHeading": "string",
        "radius": "string",
        "scaling": "string",
        "spacing": "string",
        "appearance": "string",
        "neutralColor": "string",
        "styleVariant": "string",
        "labelPosition": "string",
        "inputStyle": "string",
        "inputColor": "string",
        "cardVariant": "string",
        "cardColor": "string",
        "highContrast": true
      }
    },
    "locales": ["en"]
  },
  "preview": true,
  "access": {
    "tier": "anonymous",
    "method": "email_code"
  }
}

sendAnonymousChatMessage​

POST /v1/messages

const { data } = await client.sendAnonymousChatMessage(
  null,
  {
    request_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    message: 'string',
    locale: 'en',
    simple_language: true
  },
)

getChatVerification​

GET /v1/verification

const { data } = await client.getChatVerification()
Response
{
  "available": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "anonymous",
  "challenge_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code_expires_at": 0,
  "resend_after": 0,
  "email": "user@example.com",
  "contact_resolution": "matched",
  "access": {
    "tier": "anonymous",
    "method": "email_code"
  }
}

startChatEmailVerification​

POST /v1/verification/email

const { data } = await client.startChatEmailVerification(
  null,
  {
    request_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    email: 'user@example.com',
    locale: 'en'
  },
)
Response
{
  "available": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "anonymous",
  "challenge_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code_expires_at": 0,
  "resend_after": 0,
  "email": "user@example.com",
  "contact_resolution": "matched",
  "access": {
    "tier": "anonymous",
    "method": "email_code"
  }
}

verifyChatEmailCode​

POST /v1/verification/code

const { data } = await client.verifyChatEmailCode(
  null,
  {
    challenge_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    code: 'string'
  },
)
Response
{
  "available": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "anonymous",
  "challenge_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code_expires_at": 0,
  "resend_after": 0,
  "email": "user@example.com",
  "contact_resolution": "matched",
  "access": {
    "tier": "anonymous",
    "method": "email_code"
  }
}

cancelChatVerification​

POST /v1/verification/cancel

const { data } = await client.cancelChatVerification()
Response
{
  "available": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "anonymous",
  "challenge_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code_expires_at": 0,
  "resend_after": 0,
  "email": "user@example.com",
  "contact_resolution": "matched",
  "access": {
    "tier": "anonymous",
    "method": "email_code"
  }
}

getChatPortalLogin​

GET /v1/login/portal

const { data } = await client.getChatPortalLogin()
Response
{
  "available": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "anonymous",
  "challenge_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code_expires_at": 0,
  "attempts_left": 0,
  "email": "user@example.com",
  "contact_resolution": "matched",
  "access": {
    "tier": "anonymous",
    "method": "email_code"
  }
}

getChatPortalJourneyToken​

GET /v1/login/portal/journey-token

const { data } = await client.getChatPortalJourneyToken()
Response
{
  "id_token": "string",
  "expires_at": 0
}

startChatPortalLogin​

POST /v1/login/portal/start

const { data } = await client.startChatPortalLogin(
  null,
  {
    request_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    email: 'user@example.com'
  },
)
Response
{
  "available": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "anonymous",
  "challenge_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code_expires_at": 0,
  "attempts_left": 0,
  "email": "user@example.com",
  "contact_resolution": "matched",
  "access": {
    "tier": "anonymous",
    "method": "email_code"
  }
}

verifyChatPortalLogin​

POST /v1/login/portal/verify

const { data } = await client.verifyChatPortalLogin(
  null,
  {
    challenge_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    code: 'string'
  },
)
Response
{
  "available": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "anonymous",
  "challenge_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code_expires_at": 0,
  "attempts_left": 0,
  "email": "user@example.com",
  "contact_resolution": "matched",
  "access": {
    "tier": "anonymous",
    "method": "email_code"
  }
}

cancelChatPortalLogin​

POST /v1/login/portal/cancel

const { data } = await client.cancelChatPortalLogin()
Response
{
  "available": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "anonymous",
  "challenge_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code_expires_at": 0,
  "attempts_left": 0,
  "email": "user@example.com",
  "contact_resolution": "matched",
  "access": {
    "tier": "anonymous",
    "method": "email_code"
  }
}

signOutChatCustomer​

POST /v1/login/sign-out

const { data } = await client.signOutChatCustomer()
Response
{
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "access": {
    "tier": "anonymous",
    "method": "email_code"
  }
}

getChatAction​

GET /v1/actions

const { data } = await client.getChatAction()
Response
{
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "none",
  "action_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "revision": 0,
  "options": [
    {
      "meter_id": "string",
      "counter_id": "string",
      "meter_number": "string",
      "label": "string",
      "unit": "string",
      "min_value": 0,
      "max_value": 0
    }
  ],
  "values": {
    "meter_id": "string",
    "counter_id": "string",
    "value": 0
  },
  "field_error": "VALUE_INVALID",
  "receipt": {
    "reference": "string",
    "meter_number": "string",
    "value": 0,
    "unit": "string",
    "submitted_at": "string"
  },
  "reason": "NO_METERS"
}

startChatAction​

POST /v1/actions

const { data } = await client.startChatAction(
  null,
  {
    request_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    action_type: 'submit_meter_reading'
  },
)
Response
{
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "none",
  "action_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "revision": 0,
  "options": [
    {
      "meter_id": "string",
      "counter_id": "string",
      "meter_number": "string",
      "label": "string",
      "unit": "string",
      "min_value": 0,
      "max_value": 0
    }
  ],
  "values": {
    "meter_id": "string",
    "counter_id": "string",
    "value": 0
  },
  "field_error": "VALUE_INVALID",
  "receipt": {
    "reference": "string",
    "meter_number": "string",
    "value": 0,
    "unit": "string",
    "submitted_at": "string"
  },
  "reason": "NO_METERS"
}

reportChatActionEvent​

POST /v1/actions/events

const { data } = await client.reportChatActionEvent(
  null,
  {
    action: 'string',
    event: 'journey_submitted'
  },
)

submitChatAction​

POST /v1/actions/{action_id}/submit

const { data } = await client.submitChatAction(
  {
    action_id: 'example',
  },
  {
    expected_revision: 1,
    meter_id: 'string',
    counter_id: 'string',
    value: 0
  },
)
Response
{
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "none",
  "action_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "revision": 0,
  "options": [
    {
      "meter_id": "string",
      "counter_id": "string",
      "meter_number": "string",
      "label": "string",
      "unit": "string",
      "min_value": 0,
      "max_value": 0
    }
  ],
  "values": {
    "meter_id": "string",
    "counter_id": "string",
    "value": 0
  },
  "field_error": "VALUE_INVALID",
  "receipt": {
    "reference": "string",
    "meter_number": "string",
    "value": 0,
    "unit": "string",
    "submitted_at": "string"
  },
  "reason": "NO_METERS"
}

confirmChatAction​

POST /v1/actions/{action_id}/confirm

const { data } = await client.confirmChatAction(
  {
    action_id: 'example',
  },
  {
    expected_revision: 1
  },
)
Response
{
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "none",
  "action_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "revision": 0,
  "options": [
    {
      "meter_id": "string",
      "counter_id": "string",
      "meter_number": "string",
      "label": "string",
      "unit": "string",
      "min_value": 0,
      "max_value": 0
    }
  ],
  "values": {
    "meter_id": "string",
    "counter_id": "string",
    "value": 0
  },
  "field_error": "VALUE_INVALID",
  "receipt": {
    "reference": "string",
    "meter_number": "string",
    "value": 0,
    "unit": "string",
    "submitted_at": "string"
  },
  "reason": "NO_METERS"
}

cancelChatAction​

POST /v1/actions/{action_id}/cancel

const { data } = await client.cancelChatAction(
  {
    action_id: 'example',
  },
  {
    expected_revision: 1
  },
)
Response
{
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "none",
  "action_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "revision": 0,
  "options": [
    {
      "meter_id": "string",
      "counter_id": "string",
      "meter_number": "string",
      "label": "string",
      "unit": "string",
      "min_value": 0,
      "max_value": 0
    }
  ],
  "values": {
    "meter_id": "string",
    "counter_id": "string",
    "value": 0
  },
  "field_error": "VALUE_INVALID",
  "receipt": {
    "reference": "string",
    "meter_number": "string",
    "value": 0,
    "unit": "string",
    "submitted_at": "string"
  },
  "reason": "NO_METERS"
}

Schemas​

ListWebsiteChatsResponse​

type ListWebsiteChatsResponse = {
  website_chats: Array<{
    agent_id: string // uuid
    settings: {
      allowed_origins: { ... }
      default_locale: { ... }
      design_id?: { ... }
      authentication?: { ... }
      self_service?: { ... }
    }
    website_chat_id: string // uuid
    org_id: string
    binding_id: string // uuid
    version: number
    created_at: string // date-time
    updated_at: string // date-time
    embed: {
      script_url: { ... }
      chat_api_origin: { ... }
      demo_url: { ... }
    }
  }>
  next_cursor?: string
}

WebsiteChat​

type WebsiteChat = {
  agent_id: string // uuid
  settings: {
    allowed_origins: string[]
    default_locale: "en" | "de"
    design_id?: string // uuid
    authentication?: {
      email_code?: { ... }
      portal?: { ... }
    }
    self_service?: {
      actions: { ... }
    }
  }
  website_chat_id: string // uuid
  org_id: string
  binding_id: string // uuid
  version: number
  created_at: string // date-time
  updated_at: string // date-time
  embed: {
    script_url: string // uri
    chat_api_origin: string // uri
    demo_url: string // uri
  }
}

WebsiteChatSettings​

type WebsiteChatSettings = {
  allowed_origins: string[]
  default_locale: "en" | "de"
  design_id?: string // uuid
  authentication?: {
    email_code?: {
      email_template_id?: { ... }
    }
    portal?: {
      portal_id: { ... }
    }
  }
  self_service?: {
    actions: Array<{
      action: { ... }
      enabled: { ... }
      fulfilment: { ... }
      journey_id?: { ... }
      url?: { ... }
      access: { ... }
      guidance?: { ... }
    }>
  }
}

SelfServiceSettings​

Self-service actions customers can start in this Website Chat. On update, the list is replaced as a whole; null removes all actions.

type SelfServiceSettings = {
  actions: Array<{
    action: "submit_meter_reading" | "change_installment_rate" | "update_payment_method" | "change_billing_address" | "update_customer_details" | "change_tariff" | "report_move" | "terminate_contract"
    enabled: boolean
    fulfilment: "in_chat" | "journey" | "link"
    journey_id?: string // uuid
    url?: string
    access: "anonymous" | "identified" | "verified"
    guidance?: string
  }>
}

SelfServiceAction​

How a self-service action is done and who can start it. A journey needs journey_id, a link needs url. in_chat is only available for submit_meter_reading and requires a verified customer.

type SelfServiceAction = {
  action: "submit_meter_reading" | "change_installment_rate" | "update_payment_method" | "change_billing_address" | "update_customer_details" | "change_tariff" | "report_move" | "terminate_contract"
  enabled: boolean
  fulfilment: "in_chat" | "journey" | "link"
  journey_id?: string // uuid
  url?: string
  access: "anonymous" | "identified" | "verified"
  guidance?: string
}

WebsiteChatPreviewGrantRequest​

type WebsiteChatPreviewGrantRequest = {
  design_id?: string // uuid
  demo_customer?: boolean
}

WebsiteChatPreviewGrant​

type WebsiteChatPreviewGrant = {
  grant: string
  expires_in: number
  frame_origin: string // uri
  website_chat: {
    key: string
    assistant_name?: {
      de?: { ... }
      en?: { ... }
    }
    greeting?: {
      de?: { ... }
      en?: { ... }
    }
    defaultLocale: "en" | "de"
    login_methods: "email_code" | "portal_login"[]
    starters?: {
      de?: { ... }
      en?: { ... }
    }
    actions?: {
      meter_reading?: { ... }
      meter_reading_journey_id?: { ... }
    }
    design?: {
      id: { ... }
      last_modified_at?: { ... }
      style?: { ... }
      spark_theme?: { ... }
    }
    locales: "en" | "de"[]
  }
}

Error​

type Error = {
  error?: string
  message?: string
  details?: object
}

CreateWebsiteChatRequest​

type CreateWebsiteChatRequest = {
  agent_id: string // uuid
  settings: {
    allowed_origins: string[]
    default_locale: "en" | "de"
    design_id?: string // uuid
    authentication?: {
      email_code?: { ... }
      portal?: { ... }
    }
    self_service?: {
      actions: { ... }
    }
  }
}

UpdateWebsiteChatRequest​

type UpdateWebsiteChatRequest = {
  agent_id?: string // uuid
  settings?: {
    allowed_origins: string[]
    default_locale: "en" | "de"
    design_id?: string // uuid
    authentication?: {
      email_code?: { ... }
      portal?: { ... }
    }
    self_service?: {
      actions: { ... }
    }
  }
  version: number
}

ActionRevision​

type ActionRevision = {
  expected_revision: number
}

ActionState​

type ActionState = {
  conversation_id: string // uuid
  status: "none" | "needs_input" | "needs_confirmation" | "executing" | "completed" | "pending" | "rejected" | "handoff"
  action_id?: string // uuid
  revision?: number
  options?: Array<{
    meter_id: string
    counter_id: string
    meter_number: string
    label: string
    unit: string
    min_value?: number
    max_value?: number
  }>
  values?: {
    meter_id: string
    counter_id: string
    value: number
  }
  field_error?: "VALUE_INVALID" | "VALUE_OUT_OF_RANGE" | "TARGET_UNAVAILABLE"
  receipt?: {
    reference: string
    meter_number: string
    value: number
    unit: string
    submitted_at: string
  }
  reason?: "NO_METERS" | "SUBMISSION_REJECTED" | "SUBMISSION_UNCERTAIN"
}

VerificationState​

type VerificationState = {
  available: boolean
  conversation_id: string // uuid
  status: "anonymous" | "sending" | "pending" | "verified"
  challenge_id?: string // uuid
  code_expires_at?: number
  resend_after?: number
  email?: string // email
  contact_resolution?: "matched" | "ambiguous" | "not_found"
  access: {
    tier: "anonymous" | "identified" | "verified"
    method?: "email_code" | "portal_login" | "demo"
  }
}

PortalLoginState​

type PortalLoginState = {
  available: boolean
  conversation_id: string // uuid
  status: "anonymous" | "pending" | "verified"
  challenge_id?: string // uuid
  code_expires_at?: number
  attempts_left?: number
  email?: string // email
  contact_resolution?: "matched" | "not_found"
  access: {
    tier: "anonymous" | "identified" | "verified"
    method?: "email_code" | "portal_login" | "demo"
  }
}

LoginMethod​

How a customer can log in or verify themselves in the chat.

type LoginMethod = "email_code" | "portal_login"

AccessMethod​

How the current customer identity was established. demo is the fictional, verified customer of an Agent Builder preview; it is never a login method.

type AccessMethod = "email_code" | "portal_login" | "demo"

AccessTier​

anonymous: no customer identity. identified: the Contact is known but ownership is not proven. verified: ownership is proven (an email code or a portal login), or the demo customer of an Agent Builder preview.

type AccessTier = "anonymous" | "identified" | "verified"

CustomerAccess​

type CustomerAccess = {
  tier: "anonymous" | "identified" | "verified"
  method?: "email_code" | "portal_login" | "demo"
}

StarterQuestions​

At most six. (No maxItems, which generated clients turn into fixed-length tuples.)

type StarterQuestions = string[]

PublicWebsiteChat​

type PublicWebsiteChat = {
  key: string
  assistant_name?: {
    de?: string
    en?: string
  }
  greeting?: {
    de?: string
    en?: string
  }
  defaultLocale: "en" | "de"
  login_methods: "email_code" | "portal_login"[]
  starters?: {
    de?: string[]
    en?: string[]
  }
  actions?: {
    meter_reading?: boolean
    meter_reading_journey_id?: string // uuid
  }
  design?: {
    id: string // uuid
    last_modified_at?: string
    style?: {
      palette?: { ... }
      typography?: { ... }
      shape?: { ... }
    }
    spark_theme?: {
      accentColor?: { ... }
      backgroundColor?: { ... }
      fontBody?: { ... }
      fontHeading?: { ... }
      radius?: { ... }
      scaling?: { ... }
      spacing?: { ... }
      appearance?: { ... }
      neutralColor?: { ... }
      styleVariant?: { ... }
      labelPosition?: { ... }
      inputStyle?: { ... }
      inputColor?: { ... }
      cardVariant?: { ... }
      cardColor?: { ... }
      highContrast?: { ... }
    }
  }
  locales: "en" | "de"[]
}

WebsiteChatDesign​

type WebsiteChatDesign = {
  id: string // uuid
  last_modified_at?: string
  style?: {
    palette?: {
      primary?: { ... }
      background?: { ... }
    }
    typography?: {
      font?: { ... }
    }
    shape?: {
      border_radius?: { ... }
    }
  }
  spark_theme?: {
    accentColor?: string
    backgroundColor?: string
    fontBody?: string
    fontHeading?: string
    radius?: string
    scaling?: string
    spacing?: string
    appearance?: string
    neutralColor?: string
    styleVariant?: string
    labelPosition?: string
    inputStyle?: string
    inputColor?: string
    cardVariant?: string
    cardColor?: string
    highContrast?: boolean
  }
}

PublicEvent​

JSON payload of one SSE data frame from sendAnonymousChatMessage.

type PublicEvent = {
  type: "delta"
  text: string
  request_id: string // uuid
} | {
  type: "complete"
  text: string
  request_id: string // uuid
} | {
  type: "error"
  code: "UNAVAILABLE"
  request_id: string // uuid
} | {
  type: "action"
  action: {
    action: string
    fulfilment: "in_chat" | "journey" | "link"
    journey_id?: string // uuid
    url?: string
    access: "anonymous" | "identified" | "verified"
  }
  request_id: string // uuid
}

SelfServiceDirective​

type SelfServiceDirective = {
  action: string
  fulfilment: "in_chat" | "journey" | "link"
  journey_id?: string // uuid
  url?: string
  access: "anonymous" | "identified" | "verified"
}

PublicChatError​

type PublicChatError = {
  code: "INVALID_VERIFICATION_CODE" | "VERIFICATION_EXPIRED" | "VERIFICATION_CONFLICT" | "VERIFICATION_DISABLED" | "VERIFICATION_UNAVAILABLE" | "IDENTITY_CHANGED" | "INVALID_REQUEST" | "ORIGIN_DENIED" | "NOT_FOUND" | "INVALID_GRANT" | "SESSION_EXPIRED" | "RATE_LIMITED" | "SESSION_LIMIT" | "USAGE_LIMIT" | "REQUEST_CONFLICT" | "IN_PROGRESS" | "UNAVAILABLE" | "TEMPORARILY_UNAVAILABLE" | "IDENTITY_REQUIRED" | "ACTION_UNAVAILABLE" | "ACTION_CONFLICT" | "ACTION_TARGET_DENIED" | "INVALID_LOGIN_CODE" | "LOGIN_EXPIRED" | "LOGIN_DISABLED" | "LOGIN_UNAVAILABLE" | "LOGIN_CONFLICT" | "LOGIN_REJECTED"
  attempts_left?: number
}