Skip to content

Commit 2356c30

Browse files
jhaaaajhaaaa
authored
Merge branch 'main' into 09-03-add_docs_around_pagination_of_the_conversation_list
2 parents 8ec063a + 5a74188 commit 2356c30

37 files changed

+9707
-9026
lines changed

‎cspell.config.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,14 @@
3232
"convo",
3333
"Dmby",
3434
"darkmode",
35+
"elizaos",
3536
"ensdomains",
3637
"extname",
3738
"Fatalf",
3839
"funder",
3940
"geoblocking",
4041
"groupname",
42+
"groupstate",
4143
"hexlify",
4244
"hijklmn",
4345
"HMAC",
@@ -65,9 +67,11 @@
6567
"permissionless",
6668
"Preconfiguration",
6769
"println",
70+
"reconnections",
6871
"retryable",
6972
"scammy",
7073
"spammy",
74+
"sqlcipher",
7175
"sqlitecipher",
7276
"sslmode",
7377
"streammessage",

‎docs/pages/agents/build-agents/create-a-client.mdx‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Create an XMTP agent
2+
3+
Create an XMTP agent that can use the signing capabilities provided by a signer. This signer links the agent to the appropriate EOA or SCW.
4+
5+
## Create an EOA signer
6+
7+
```tsx [Node]
8+
import { Agent } from '@xmtp/agent-sdk';
9+
import { createSigner, createUser } from '@xmtp/agent-sdk/user';
10+
import { getRandomValues } from 'node:crypto';
11+
12+
// Option 1: Create a local user + signer
13+
const user = createUser('0xprivateKey');
14+
const signer = createSigner(user);
15+
16+
const agent = await Agent.create(signer, {
17+
env: 'dev', // or 'production'
18+
dbEncryptionKey: getRandomValues(new Uint8Array(32)), // save it for later
19+
});
20+
```
21+
22+
## Environment variables
23+
24+
The XMTP Agent SDK allows you to use environment variables (`process.env`) for easier configuration without modifying code.
25+
26+
**Available variables:**
27+
28+
| Variable | Purpose | Example |
29+
| ------------------------ | -------------------------------------------------------------- | --------------------------------------- |
30+
| `XMTP_WALLET_KEY` | Private key for wallet | `XMTP_WALLET_KEY=0x1234...abcd` |
31+
| `XMTP_ENV` | XMTP network environment (`local`, `dev`, or `production`) | `XMTP_ENV=dev` or `XMTP_ENV=production` |
32+
| `XMTP_DB_ENCRYPTION_KEY` | Database encryption key for the local database (32 bytes, hex) | `XMTP_DB_ENCRYPTION_KEY=0xabcd...1234` |
33+
34+
Using the environment variables, you can setup your agent in just a few lines of code:
35+
36+
### Generate random keys
37+
38+
```tsx [Node]
39+
import { generatePrivateKey } from 'viem';
40+
import { getRandomValues } from 'node:crypto';
41+
42+
const walletKey = generatePrivateKey();
43+
const encryptionKeyHex = getRandomValues(new Uint8Array(32));
44+
45+
console.log('Wallet key:', walletKey);
46+
console.log('Encryption key:', encryptionKeyHex);
47+
```
48+
49+
Use this [script to generate](https://github.com/ephemeraHQ/xmtp-agent-examples) random XMTP keys:
50+
51+
```bash
52+
yarn gen:keys
53+
```
54+
55+
> Running the gen:keys command will append keys to your existing .env file.
56+
57+
### Use environment variables
58+
59+
```tsx [Node]
60+
// Load variables from .env file
61+
process.loadEnvFile('.env');
62+
63+
// Create agent using environment variables
64+
const agent = await Agent.createFromEnv();
65+
```
66+
67+
## Configuration options
68+
69+
### Configure an XMTP client
70+
71+
You can configure an XMTP client with these options passed to `Agent.create`:
72+
73+
```tsx [Node]
74+
/**
75+
* Specify which XMTP environment to connect to. (default: `dev`)
76+
*/
77+
env?: 'local' | 'dev' | 'production';
78+
/**
79+
* Add a client app version identifier that's included with API requests.
80+
* Production apps are strongly encouraged to set this value.
81+
*
82+
* You can use the following format: `appVersion: 'AGENT_NAME/AGENT_VERSION'`.
83+
* For example, `appVersion: 'alix/2.x'`
84+
*
85+
* If you have an agent and an app, it's best to distinguish them from each other by
86+
* adding `-agent` and `-app` to the names. For example:
87+
* - Agent: `appVersion: 'alix-agent/2.x'`
88+
* - App: `appVersion: 'alix-app/3.x'`
89+
*
90+
* Setting this value provides telemetry that shows which agents are using the
91+
* XMTP client SDK. This information can help XMTP core developers provide you with agent
92+
* support, especially around communicating important SDK updates, including
93+
* deprecations and required upgrades.
94+
*/
95+
appVersion?: string;
96+
/**
97+
* apiUrl can be used to override the `env` flag and connect to a
98+
* specific endpoint
99+
*/
100+
apiUrl?: string;
101+
/**
102+
* Path to the local DB
103+
*
104+
* There are 4 value types that can be used to specify the database path:
105+
*
106+
* - `undefined` (or excluded from the client options)
107+
* The database will be created in the current working directory and is based on
108+
* the XMTP environment and client inbox ID.
109+
* Example: `xmtp-dev-<inbox-id>.db3`
110+
*
111+
* - `null`
112+
* No database will be created and all data will be lost once the client disconnects.
113+
*
114+
* - `string`
115+
* The given path will be used to create the database.
116+
* Example: `./my-db.db3`
117+
*
118+
* - `function`
119+
* A callback function that receives the inbox ID and returns a string path.
120+
* Example: `(inboxId) => string`
121+
*/
122+
dbPath?: string | null | ((inboxId: string) => string);
123+
/**
124+
* Encryption key for the local DB
125+
*/
126+
dbEncryptionKey?: Uint8Array;
127+
/**
128+
* Allow configuring codecs for additional content types
129+
*/
130+
codecs?: ContentCodec[];
131+
/**
132+
* Enable structured JSON logging
133+
*/
134+
structuredLogging?: boolean;
135+
/**
136+
* Logging level
137+
*/
138+
loggingLevel?: LogLevel;
139+
```
140+
141+
## Create a smart contract wallet (SCW) signer
142+
143+
When working with smart contract wallets, you can create an XMTP agent using the wallet's seed or private key:
144+
145+
```tsx [Node]
146+
import { Agent } from '@xmtp/agent-sdk';
147+
import { createSigner, createUser } from '@xmtp/agent-sdk/user';
148+
149+
const walletData = await initializeWallet('wallet.json');
150+
/* Create the signer using viem and parse the encryption key for the local db */
151+
const user = createUser(walletData.seed as `0x${string}`);
152+
const signer = createSigner(user);
153+
154+
// Create agent with SCW signer
155+
const agent = await Agent.create(signer);
156+
157+
/* Add your own business logic here */
158+
```

‎docs/pages/agents/build-agents/create-conversations.mdx‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Create conversations
2+
3+
With your agent, you can create a new conversation, whether it's a group chat or direct message (DM).
4+
5+
## Create a new group chat
6+
7+
Once you have the verified identities, create a new group chat. The maximum group chat size is 250 members.
8+
9+
### By Ethereum address
10+
11+
```js [Node]
12+
const group = await agent.createGroupWithAddresses(
13+
[bo.address, caro.address],
14+
createGroupOptions /* optional */
15+
);
16+
```
17+
18+
### By inbox ID
19+
20+
```js [Node]
21+
const group = await agent.client.conversations.newGroup(
22+
[bo.inboxId, caro.inboxId],
23+
createGroupOptions /* optional */
24+
);
25+
```
26+
27+
## Create a new DM
28+
29+
Once you have the verified identity, get its inbox ID and create a new DM:
30+
31+
### By Ethereum address
32+
33+
```js [Node]
34+
// by Ethereum address
35+
const dm = await agent.createDmWithAddress({
36+
identifier: bo.accountAddress,
37+
identifierKind: IdentifierKind.Ethereum,
38+
});
39+
```
40+
41+
### By inbox ID
42+
43+
```js [Node]
44+
const dm = await agent.client.conversations.newDm(bo.inboxId);
45+
```
46+
47+
### Get the address of the sender
48+
49+
```ts [Node]
50+
import { getTestUrl } from '@xmtp/agent-sdk/debug';
51+
52+
agent.on('text', async (ctx) => {
53+
const senderAddress = ctx.getSenderAddress();
54+
console.log('Message from:', senderAddress);
55+
});
56+
```
57+
58+
## Conversation helper methods
59+
60+
Use these helper methods to quickly locate and access specific conversations—whether by conversation ID, topic, group ID, or DM identity—returning the appropriate ConversationContainer, group, or DM object.
61+
62+
```js [Node]
63+
// get a conversation by its ID
64+
const conversationById =
65+
await agent.client.conversations.getConversationById(conversationId);
66+
67+
// get a message by its ID
68+
const messageById = await agent.client.conversations.getMessageById(messageId);
69+
70+
// get a 1:1 conversation by a peer's inbox ID
71+
const dmByInboxId =
72+
await agent.client.conversations.getDmByInboxId(peerInboxId);
73+
```
74+
75+
## Check if an identity is reachable
76+
77+
The first step to creating a conversation is to verify that participants' identities are reachable on XMTP. The `canMessage` method checks each identity's compatibility, returning a response indicating whether each identity can receive messages.
78+
79+
```js [Node]
80+
import { Agent, IdentifierKind } from '@xmtp/agent-sdk';
81+
82+
const agent = await Agent.createFromEnv();
83+
84+
// response is a Map of string (identifier) => boolean (is reachable)
85+
const response = await agent.client.canMessage([
86+
{
87+
identifier: '0xcaroAddress',
88+
identifierKind: IdentifierKind.Ethereum,
89+
},
90+
]);
91+
```

0 commit comments

Comments
 (0)