Langbase

Thread Messages: Append v1

The Append Messages API allows you to add new messages to an existing thread. This is essential for building interactive chat experiences and maintaining conversation history in your applications.

The Append Messages API supports:

  • Adding user messages to represent input from your users
  • Adding assistant messages to represent AI responses
  • Adding system messages to guide conversation behavior
  • Adding tool messages to represent function call results
  • Including metadata and attachments with messages

Generate a User/Org API key

You will need to generate an API key to authenticate your requests. For more information, visit the User/Org API key documentation.

POST/v1/threads/{threadId}/messages

Append messages to a thread

Add new messages to an existing thread.

Headers

  • Name
    Content-Type
    Type
    string
    Required
    Required
    Description

    Request content type. Needs to be application/json

  • Name
    Authorization
    Type
    string
    Required
    Required
    Description

    Replace LANGBASE_API_KEY with your User/Org API key

Path Parameters

  • Name
    threadId
    Type
    string
    Required
    Required
    Description

    The unique identifier of the thread to append messages to.

Body Parameters

  • Name
    messages
    Type
    Array<ThreadMessage>
    Required
    Required
    Description

    An array containing message objects to append to the thread.

    ThreadMessage Object

    interface ThreadMessage extends Message {
  attachments?: any[];
  metadata?: Record<string, string>;
}

interface Message {
  role: 'user' | 'assistant' | 'system' | 'tool';
  content: string | null;
  name?: string;
  tool_call_id?: string;
  tool_calls?: ToolCall[];
}
    • Name
      role
      Type
      string
      Required
      Required
      Description

      The role of the message author: system | user | assistant | tool

    • Name
      content
      Type
      string | null
      Required
      Required
      Description

      The content of the message. Can be null for tool calls.

    • Name
      name
      Type
      string
      Description

      Optional name identifier for the message author.

    • Name
      tool_call_id
      Type
      string
      Description

      ID of the tool call this message is responding to, if applicable.

    • Name
      tool_calls
      Type
      Array<ToolCall>
      Description

      Tool calls made in this message, if any.

      ToolCall Object

      interface ToolCall {
  id: string;
  type: 'function';
  function: {
    name: string;
    arguments: string;
  };
}
    • Name
      attachments
      Type
      Array<any>
      Description

      Optional attachments for the message.

    • Name
      metadata
      Type
      Record<string, string>
      Description

      Optional metadata for the message.

Usage example

Install the SDK

npm i langbase

Environment variables

.env file

LANGBASE_API_KEY="<USER/ORG-API-KEY>"

Append messages to a thread

Basic message append

POST
/v1/threads/{threadId}/messages
import { Langbase } from 'langbase';

const langbase = new Langbase({
  apiKey: process.env.LANGBASE_API_KEY // Your User/Org API key
});

async function main() {
  const threadId = "thread_abc123xyz456";
  const messages = await langbase.threads.append({
    threadId: threadId,
    messages: [{
      role: "user",
      content: "I have a question about my order #12345"
    }]
  });

  console.log('Messages appended:', messages);
  return messages;
}

main();

Response

The response is an array of ThreadMessagesBaseResponse objects representing the newly added messages.

  • Name
    id
    Type
    string
    Description

    The unique identifier for the message.

  • Name
    thread_id
    Type
    string
    Description

    The ID of the thread that this message belongs to.

  • Name
    created_at
    Type
    number
    Description

    The Unix timestamp (in seconds) for when the message was created.

  • Name
    role
    Type
    string
    Description

    The role of the message author. One of 'user', 'assistant', 'system', or 'tool'.

  • Name
    content
    Type
    string | null
    Description

    The content of the message. Will be null for messages that only contain tool calls.

  • Name
    tool_call_id
    Type
    string | null
    Description

    If the message is a tool response, this is the ID of the tool call it is responding to.

  • Name
    tool_calls
    Type
    Array<ToolCall> | []
    Description

    If the message contains tool calls, this array will contain the tools called by the assistant.

  • Name
    name
    Type
    string | null
    Description

    If the message is a tool response, this is the name of the tool that was called.

  • Name
    attachments
    Type
    Array<any> | []
    Description

    Any attachments associated with the message.

  • Name
    metadata
    Type
    Record<string, string> | {}
    Description

    Key-value pairs of metadata associated with the message.

Response Example - Single Message

[
 {
   "id": "msg_abc123xyz456",
   "thread_id": "thread_abc123xyz456",
   "created_at": 1714322048,
   "role": "user",
   "content": "I have a question about my order #12345",
   "tool_call_id": null,
   "tool_calls": [],
   "name": null,
   "attachments": [],
   "metadata": {}
 }
]

Response Example - Multiple Messages

[
  {
    "id": "msg_abc123xyz456",
    "thread_id": "thread_abc123xyz456",
    "created_at": 1714322048,
    "role": "user",
    "content": "Can you help me with my account?",
    "tool_call_id": null,
    "tool_calls": [],
    "name": null,
    "attachments": [],
    "metadata": {}
  },
  {
    "id": "msg_def456uvw789",
    "thread_id": "thread_abc123xyz456",
    "created_at": 1714322048,
    "role": "assistant",
    "content": "Sure, I'd be happy to help with your account. What specific issue are you having?",
    "tool_call_id": null,
    "tool_calls": [],
    "name": null,
    "attachments": [],
    "metadata": {}
  },
  {
    "id": "msg_ghi789rst012",
    "thread_id": "thread_abc123xyz456",
    "created_at": 1714322048,
    "role": "user",
    "content": "I can't reset my password.",
    "tool_call_id": null,
    "tool_calls": [],
    "name": null,
    "attachments": [],
    "metadata": {}
  }
]