Working with Users

What a User is

A User is a person in your application who sends and receives messages through Surge’s embeddable UI components. Users are provisioned via the Surge API and belong to a specific account. They are separate from people who log in to hq.surge.app. If you’re building a SaaS platform where your customers interact with Surge-powered messaging, Users are typically your customers’ employees, not your customers’ own customers. Users are used in two ways:

Embedded UI: the inbox and conversation components authenticate as a specific User, showing that user’s conversations and sending messages on their behalf
Attribution: messages and calls can be tied to a User, so you can trace activity back to the individual

Users do not have Surge passwords or sessions. Authentication for embedded components goes through a short-lived JWT that your server generates.

Provision a User

Create a User via the API before you mount any components for them:

from surge import Surge

surge = Surge()

user = surge.users.create(
    account_id="{account_id}",
    first_name="Jordan",
    last_name="Patel",
    metadata={"internal_user_id": "u_9887"},
)

import Surge from "@surgeapi/node";

const surge = new Surge();

const user = await surge.users.create("{account_id}", {
  first_name: "Jordan",
  last_name: "Patel",
  metadata: { internal_user_id: "u_9887" },
});

require "surge_api"

surge = SurgeAPI::Client.new

user = surge.users.create(
  "{account_id}",
  first_name: "Jordan",
  last_name: "Patel",
  metadata: { "internal_user_id" => "u_9887" }
)

client = Surge.Client.new(System.get_env("SURGE_API_KEY"))

{:ok, user} =
  Surge.Users.create(client, "{account_id}", %{
    first_name: "Jordan",
    last_name: "Patel",
    metadata: %{internal_user_id: "u_9887"}
  })

curl -X POST https://api.surge.app/accounts/{account_id}/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jordan",
    "last_name": "Patel",
    "metadata": {
      "internal_user_id": "u_9887"
    }
  }'

{
  "id": "usr_01jrzhe8d9enptypyx360pcmxu",
  "first_name": "Jordan",
  "last_name": "Patel",
  "metadata": {
    "internal_user_id": "u_9887"
  }
}

Store the returned id alongside the user’s record in your database. You’ll use it to generate component tokens and attribute messages.

Generate a component token

Your server generates a short-lived JWT for each user session. The JWT scopes the embedded component to that specific user’s data. The simplest path is the token endpoint:

response = surge.users.create_token(user_id="{user_id}")
token = response.token

const response = await surge.users.createToken("{user_id}");
const token = response.token;

response = surge.users.create_token("{user_id}")
token = response.token

{:ok, token} = Surge.Users.create_token(client, "{user_id}", %{})

curl -X POST https://api.surge.app/users/{user_id}/tokens \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "token": "eyJhbGciOiJFZERTQSIsImtpZCI6InNnbl8wMWouLi4ifQ..."
}

Return this token to your frontend and use it to mount the component. Generate a new token on each page load because tokens are short-lived.

Typical vertical SaaS flow

When one of your customer’s employees is added to your SaaS product, create a Surge User via POST /accounts/{account_id}/users. Store the id.
When that employee loads a page in your app that includes embedded messaging, your server calls POST /users/{user_id}/tokens to get a fresh JWT.
Your frontend receives the JWT and mounts the Surge Inbox or Conversation component with it.
The component shows only that user’s conversations and sends messages attributed to them.

# On page load, server-side
@app.get("/api/surge-token")
async def get_surge_token(current_user: User):
    response = surge.users.create_token(user_id=current_user.surge_user_id)
    return {"token": response.token}

<iframe
  id="surge-inbox"
  title="Surge conversations"
  src="https://embed.surge.app/conversations"
></iframe>

<script type="module">
  const { token } = await fetch("/api/surge-token").then((response) =>
    response.json()
  );

  const userId = "{SURGE_USER_ID}";
  const embedUrl = new URL("https://embed.surge.app/conversations");
  embedUrl.searchParams.set("user_id", userId);
  embedUrl.searchParams.set("token", token);

  document.getElementById("surge-inbox").src =
    embedUrl.toString();
</script>

List and manage Users

# List users in an account
for user in surge.users.list(account_id="{account_id}"):
    print(user.id)

# Update a user
surge.users.update("{user_id}", first_name="Jordan M.")

# Delete a user
surge.users.delete("{user_id}")

// List users in an account
for await (const user of await surge.users.list("{account_id}")) {
  console.log(user.id);
}

// Update a user
await surge.users.update("{user_id}", { first_name: "Jordan M." });

// Delete a user
await surge.users.delete("{user_id}");

# List users in an account
page = surge.users.list("{account_id}")
page.data.each { |u| puts u.id }

# Update a user
surge.users.update("{user_id}", first_name: "Jordan M.")

# Delete a user
surge.users.delete("{user_id}")

# Surge.Users.list isn't typed in the Elixir SDK yet — use the raw client.
{:ok, page} =
  Surge.Client.request(client, :get, "/accounts/{account_id}/users")

Enum.each(page["data"], fn u -> IO.puts(u["id"]) end)

# Update a user
{:ok, _} = Surge.Users.update(client, "{user_id}", %{first_name: "Jordan M."})

# Delete a user
{:ok, _} = Surge.Users.delete(client, "{user_id}")

# List users in an account
curl "https://api.surge.app/accounts/{account_id}/users" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update a user
curl -X PATCH https://api.surge.app/users/{user_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Jordan M." }'

# Delete a user
curl -X DELETE https://api.surge.app/users/{user_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting a User removes their Surge record but does not delete message history.

Next steps

Inbox component

Mount a conversation list for the current User.

Conversation component

Mount a single threaded conversation view.

Unread Count component

Show a live unread badge in your navigation.

Get started

Register your business

Sending messages

Receiving messages & webhooks

Phone numbers

Verifications

Channels roadmap

Embeddable UI components

Concepts

Working with Users

What a User is

Provision a User

Generate a component token

Typical vertical SaaS flow

List and manage Users

Next steps

Inbox component

Conversation component

Unread Count component

​What a User is

​Provision a User

​Generate a component token

​Typical vertical SaaS flow

​List and manage Users

​Next steps

Inbox component

Conversation component

Unread Count component

What a User is

Provision a User

Generate a component token

Typical vertical SaaS flow

List and manage Users

Next steps