TalknoteRb

A Ruby client library for the Talknote API. This gem provides a simple interface to interact with Talknote's REST API, allowing you to access direct messages, groups, and other Talknote features programmatically.

• 🔐 OAuth 2.0 authentication flow
• 💬 Direct message management
• 👥 Group conversation access
• 📊 Unread message tracking
• 🖥️ Command-line interface
• 💎 Simple Ruby API client

Add this line to your application's Gemfile:

gem 'talknote_rb'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install talknote_rb

Note: The CSV export examples require the csv gem, which is included as a dependency. If you're using Ruby 3.0+, make sure to include it in your Gemfile:

gem 'csv', '~> 3.0'

1. Get your client credentials from the Talknote Developer Console
2. Run the authentication setup:

   bundle exec talknote init -i your_client_id -s your_client_secret

3. Start using the API:

   bundle exec talknote dm

Before using the API, you need to set up authentication. First, obtain your client credentials from the Talknote Developer Console.

To initialize and authenticate, run:

bundle exec talknote init -i your_client_id -s your_client_secret

This command will:

1. Open your browser to the Talknote OAuth authorization page
2. Start a local server to handle the OAuth callback
3. Save your access token to ~/.config/talknote/token.json

You can also specify custom host and port for the OAuth callback:

bundle exec talknote init -i your_client_id -s your_client_secret -h localhost -p 8080

# Initialize authentication (run this first)
talknote init -i CLIENT_ID -s CLIENT_SECRET

# Optional: specify custom callback host/port
talknote init -i CLIENT_ID -s CLIENT_SECRET -h localhost -p 9000

# List all DM conversations
talknote dm

# Show messages from a specific DM conversation
talknote dm-list DM_ID

# Show unread count for a DM conversation
talknote dm-unread DM_ID

# Send a message to a DM conversation
talknote dm-post DM_ID "Your message here"

# List all groups
talknote group

# Show messages from a specific group
talknote group-list GROUP_ID

# Show unread count for a group
talknote group-unread GROUP_ID

# Send a message to a group
talknote group-post GROUP_ID "Your message here"

require 'talknote_rb'

# Client will automatically load token from ~/.config/talknote/token.json
client = Talknote::Client.new

# Get all DM conversations
conversations = client.dm

# Get messages from a specific conversation
messages = client.dm_list('conversation_id')

# Send a message
result = client.dm_post('conversation_id', 'Hello!')

# Get all groups
groups = client.group

# Get messages from a specific group
messages = client.group_list('group_id')

# Get unread count
unread_count = client.group_unread('group_id')

# Send a message to a group
result = client.group_post('group_id', 'Hello group!')

⚠️ Important Notes for CSV Export:

• API rate limit warning: Export operations are constrained by API rate limits (500 requests per 24 hours per user)
• Large numbers of conversations may consume significant API quota and take time to export
• You must implement appropriate rate limiting delays between requests to avoid hitting API limits
• If the process stops unexpectedly, wait some time before re-running to avoid further rate limiting
• Each API call is logged with progress indicators to track export status
• Export can be interrupted with Ctrl+C and resumed later
• For very large exports approaching the 500 request limit, consider running the specific DM or Group exporters separately instead of the complete export
• Monitor your API usage to stay within the 24-hour limit of 500 requests

The CSV export examples will create files with the following structure:

DM CSV format:

• conversation_id, conversation_name, message_id, user_id, user_name, message, created_at, message_type

Group CSV format:

• group_id, group_name, message_id, user_id, user_name, message, created_at, message_type, unread_count

The examples/ directory contains practical usage examples:

• examples/dm_example.rb - Basic DM operations
• examples/group_example.rb - Basic group operations
• examples/dm_csv_export_example.rb - Export all DM conversations to CSV
• examples/group_csv_export_example.rb - Export all group conversations to CSV
• examples/complete_csv_export_example.rb - Export everything to organized CSV files

# Export all DM conversations to CSV
ruby examples/dm_csv_export_example.rb

# Export all group conversations to CSV
ruby examples/group_csv_export_example.rb

# Export everything to organized directory
ruby examples/complete_csv_export_example.rb

begin
  result = client.dm
rescue Talknote::Error => e
  puts "API Error: #{e.message}"
end

The authentication token is stored in ~/.config/talknote/token.json after running the init command. The file contains the OAuth 2.0 access token and refresh token.

⚠️ Important: The Talknote API has rate limits per user:

• API execution limit: 500 requests per 24 hours per user

Please be mindful of these limits when using the API, especially when performing bulk operations like CSV exports or automated tasks. When implementing bulk operations, ensure you add appropriate rate limiting delays between requests to avoid hitting these limits.

This gem supports the following Talknote API endpoints:

• GET /api/v1/dm - List DM conversations
• GET /api/v1/dm/list/:id - Get messages from a conversation
• GET /api/v1/dm/unread/:id - Get unread count
• POST /api/v1/dm/post/:id - Send a message

• GET /api/v1/group - List groups
• GET /api/v1/group/list/:id - Get messages from a group
• GET /api/v1/group/unread/:id - Get unread count
• POST /api/v1/group/post/:id - Send a message to group

Make sure your Talknote application has the necessary scopes:

• talknote.direct_message
• talknote.direct_message.read
• talknote.direct_message.write
• talknote.direct_message.unread
• talknote.direct_message.message.read
• talknote.direct_message.message.write

• talknote.group
• talknote.group.read
• talknote.group.write
• talknote.group.unread
• talknote.group.message.read
• talknote.group.message.write

• talknote.user.read
• talknote.user.write
• talknote.timeline.read
• talknote.timeline.write
• talknote.timeline.message.read
• talknote.timeline.message.write
• talknote.timeline.unread
• talknote.allfeed.read
• talknote.allfeed.unread

require 'talknote_rb'

client = Talknote::Client.new

# Get all groups and find the right one
groups = client.group
group = groups.dig('data', 'groups')&.find { |g| g['name'].include?('Daily Reports') }

if group
  # Send daily report
  report = "📊 Daily Report (#{Date.today})\n\n" \
           "- Tasks completed: 15\n" \
           "- Issues resolved: 3\n" \
           "- New features deployed: 2"

  client.group_post(group['id'], report)
  puts "Daily report sent to #{group['name']}!"
else
  puts "Daily Reports group not found"
end

require 'talknote_rb'

client = Talknote::Client.new

# Check unread DMs
dm_conversations = client.dm
dm_conversations.dig('data', 'threads')&.each do |dm|
  unread = client.dm_unread(dm['id'])
  unread_count = unread.dig('data', 'unread_count')

  if unread_count && unread_count > 0
    puts "📩 #{dm['title']}: #{unread_count} unread messages"
  end
end

# Check unread group messages
groups = client.group
groups.dig('data', 'groups')&.each do |group|
  unread = client.group_unread(group['id'])
  unread_count = unread.dig('data', 'unread_count')

  if unread_count && unread_count > 0
    puts "👥 #{group['name']}: #{unread_count} unread messages"
  end
end

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/geeknees/talknote_rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the TalknoteRb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.