Skip to Content
Building AppsSDK GuideMessaging

Messaging

🚧

Coming Soon — The ChainSocial SDK is not yet published. This documentation describes the planned API. Use the REST API for current integrations.

Send direct messages between users on-chain.

Sending Messages

Inline Messages

For text messages up to 4KB:

await client.directMessage.sendInlineMessage(
  recipientAddress,
  'Hey, great post today!'
)

With Content ID

For larger messages or media:

// Create content first
const contentId = await client.content.createInlineContent('Hello!')
 
// Send with content reference
await client.directMessage.sendMessage(recipientAddress, contentId)

Reading Messages (API)

Message endpoints require authentication. The API validates that you’re requesting your own messages.

List Conversations

Get all conversations for the authenticated user:

const response = await fetch(
  `https://api.chainsocial.cc/api/messages/${myAddress}/conversations`,
  {
    headers: {
      'Authorization': `Bearer ${authToken}`  // If using API auth
    }
  }
)
const data = await response.json()
 
for (const convo of data.items) {
  console.log(`Chat with @${convo.peer?.username}`)
  console.log(`Last message: ${convo.lastMessage?.content}`)
  console.log(`Unread: ${convo.unreadCount}`)
}

Conversation Response Structure

{
  "items": [
    {
      "participant1": "0x...",
      "participant2": "0x...",
      "peerAddress": "0x...",
      "peer": {
        "address": "0x...",
        "username": "bob",
        "metadata": { "displayName": "Bob" }
      },
      "lastMessageAt": 1704153600,
      "messageCount": 42,
      "unreadCount": 3,
      "lastMessage": {
        "messageId": "0x...",
        "sender": "0x...",
        "content": "Hey!",
        "sentAt": 1704153600
      }
    }
  ]
}

Get Messages with a Specific User

const response = await fetch(
  `https://api.chainsocial.cc/api/messages/${myAddress}/with/${peerAddress}?limit=50`,
  {
    headers: { 'Authorization': `Bearer ${authToken}` }
  }
)
const data = await response.json()
 
for (const msg of data.items) {
  const direction = msg.sender === myAddress ? 'Sent' : 'Received'
  console.log(`${direction}: ${msg.content}`)
}

Message Response Structure

{
  "items": [
    {
      "messageId": "0x...",
      "sender": "0x...",
      "recipient": "0x...",
      "contentId": "0x...",
      "sentAt": 1704153600,
      "isRead": true,
      "readAt": 1704153700,
      "content": "Hello!",
      "contentStorageType": 0,
      "contentMimeType": "text/plain"
    }
  ],
  "page": {
    "limit": 50,
    "offset": 0
  }
}

Blocking and Messaging

If a user blocks another user:

  • The blocked user cannot send messages to the blocker
  • Existing messages remain visible
  • The blocker can still message the blocked user (one-way)
// This will fail if you're blocked by recipient
try {
  await client.directMessage.sendInlineMessage(recipientAddress, 'Hi!')
} catch (error) {
  if (error.message.includes('Blocked')) {
    console.log('You are blocked by this user')
  }
}

Delegation: On-Behalf-Of

Send messages as a delegate:

// Requires DM delegation permission
await client.directMessage.sendInlineMessageOnBehalfOf(
  senderAddress,      // Who the message appears from
  recipientAddress,
  'Message from assistant'
)

Common Patterns

Chat Interface

function ChatView({ peerAddress }) {
  const client = useChainSocialClient()
  const { address: myAddress } = useAccount()
  const [messages, setMessages] = useState([])
  const [newMessage, setNewMessage] = useState('')
 
  // Load messages
  useEffect(() => {
    async function loadMessages() {
      const response = await fetch(
        `/api/messages/${myAddress}/with/${peerAddress}?limit=50`
      )
      const data = await response.json()
      setMessages(data.items.reverse())  // Oldest first
    }
    loadMessages()
  }, [myAddress, peerAddress])
 
  // Send message
  const handleSend = async () => {
    if (!newMessage.trim() || !client) return
 
    await client.directMessage.sendInlineMessage(peerAddress, newMessage)
    setMessages([...messages, {
      sender: myAddress,
      content: newMessage,
      sentAt: Date.now() / 1000
    }])
    setNewMessage('')
  }
 
  return (
    <div>
      <div className="messages">
        {messages.map((msg, i) => (
          <div key={i} className={msg.sender === myAddress ? 'sent' : 'received'}>
            {msg.content}
          </div>
        ))}
      </div>
      <input
        value={newMessage}
        onChange={e => setNewMessage(e.target.value)}
        onKeyPress={e => e.key === 'Enter' && handleSend()}
      />
      <button onClick={handleSend}>Send</button>
    </div>
  )
}

New Message Indicator

async function getUnreadCount(myAddress, authToken) {
  const response = await fetch(
    `https://api.chainsocial.cc/api/messages/${myAddress}/conversations`,
    { headers: { 'Authorization': `Bearer ${authToken}` } }
  )
  const data = await response.json()
 
  return data.items.reduce((total, convo) => total + convo.unreadCount, 0)
}

Constraints

  • Cannot message yourself
  • Cannot message blocked users (if they blocked you)
  • Inline message limit: 4KB
  • Messages are stored on-chain (public to everyone with database access)

Privacy Note: While messages require authentication to read via the API, they are stored on-chain. Anyone with database/RPC access can read them. For truly private messaging, consider end-to-end encryption.

Next Steps

Social GraphAdvanced