Embedding the AI Analyst Chat

The Arcwise AI Analyst can be embedded as an iframe within your page or application using our embeddable chat page, https://sql.arcwise.app/chat-embed, as the source.

Using this method, we allow the outer frame to pass parameters into the embeddable chat page using the following query parameters.

• spreadsheet_id

  If you have used the Arcwise AI Analyst in Sheets, you may provide the Sheets spreadsheet id to chat across the connected tabs in that spreadsheet.

• table

  Instead of passing in a spreadsheet_id, you may provide fully-qualified table names in the form of table=db.schema.table to scope any new chat threads with the Arcwise AI Analyst to only those tables provided. Multiple tables can be added to the AI Analyst context by providing this query parameter multiple times like so: table=db.schema.table1&table=db.schema.table2&table=...

• custom_instructions

  This parameter may be used to provide any specific custom instructions to the Arcwise AI Analyst, which will be appended to its system context.

JWT authentication

By default, the embedded AI Analyst chat will display a Google login button and ask the user to authenticate manually.

If you'd like to allow users to skip the login flow, the embedding URL may provide a user-specific JWT token via a #token hash parameter (example: https://sql.arcwise.app/chat-embed?table=x#token=JWT_TOKEN).

JWTs must be created programmatically in your embedding code through a server-side endpoint, to avoid leaking the Embed Secret.

1. Go to https://admin.arcwise.app/#/organizations and click to Edit your organization. On the next screen, click Manage Embed Secret.

   1. Generate a new embed secret (important: you will only be shown this secret once, so you must store it securely in your application environment (e.g. as an environment variable) when it is created.

   2. Also, copy and store the organization_id in your application (this is non-sensitive).

1. Generate a JWT with the following payload format using the Embed Secret as the JWT key, and the Arcwise organization ID as the issuer, using the HS256 encryption algorithm. All fields in the payload are required.

// JWT JSON payload format
{
  "sub": "[email protected]",
  "aud": "arcwise.app",
  "iat": [current UNIX time],
  "iss": [arcwise_organization_id],
  "exp": [desired expiration time, e.g. current time + 8 hours]
}

• "sub" should be the user's Google account email address. It must match the Google email they use to access Arcwise.

• "aud" specifies the audience for the JWT (Arcwise).

• "iat" should be the current UNIX timestamp.

• "iss" must be your Arcwise Organization ID from above.

• "exp" determines how long the JWT will be valid. The user will be logged out of the iframe after this time, so we recommend setting this to a fairly large number of hours (depending on your organization's security policy).

Example with the PyJWT Python library

import jwt
import time

# Replace these with the values from the admin dashboard
arcwise_embed_secret = "00000000-0000-0000-0000-000000000000"
arcwise_organization_id = "12345678-1234-5678-4321-000000000000"
# viewer's email
user_email = "[email protected]"
token_expiration_time = 8 * 3600  # 8 hours

# Generate a JWT
current_timestamp = int(time.time())
arcwise_token = jwt.encode({
    "sub": user_email,
    "aud": "arcwise.app",
    "iat": current_timestamp,
    "iss": arcwise_organization_id,
    "exp": current_timestamp + token_expiration_time,
}, arcwise_embed_secret, algorithm="HS256")

# Embedding URL
embed_url = f"https://sql.arcwise.app/chat-embed#token={arcwise_token}"