Converse — Natural Language Queries

The Converse endpoint lets you ask the Reward Agent questions in plain English. It plans which tools to call, executes them, and synthesizes a human-readable response.

Requires: HMAC authentication + pro or enterprise tier.

Endpoints

Access Point	Endpoint
HTTP	POST https://agent.rsnc.network/converse
REST API	POST https://agent.rsnc.network/api/v1/converse
CLI	rsnc converse "your question"

How It Works

Converse uses a three-step pipeline:

1. Plan    → AI analyzes your query and selects which tools to call
2. Execute → Tools are called with extracted parameters
3. Synthesize → Results are combined into a natural language response

The agent automatically chains multiple tool calls when needed. For example, "Compare Nike and Adidas loyalty programs" triggers brand_info, brand_analytics, and compare_brands behind the scenes.

Request

curl -X POST https://agent.rsnc.network/converse \
  -H "Content-Type: application/json" \
  -H "X-RSNC-Agent-Key: your-key-id" \
  -H "X-RSNC-Timestamp: $(date +%s)" \
  -H "X-RSNC-Signature: <computed>" \
  -d '{"query": "Which brand gives the best cashback for a $100 retail purchase?"}'

Request Body

Field	Type	Required	Description
query	string	Yes	Natural language question (non-empty)

Response

{
  "response": "Based on current cashback rates across retail brands...",
  "toolsUsed": ["route_purchase", "compare_cashback"],
  "confidence": 0.95
}

Conversation Patterns

The agent recognizes five conversation patterns and optimizes tool selection accordingly:

Purchase Routing

"I want to buy running shoes for $150. Where should I shop?"

Tools used: route_purchase, compare_cashback, best_deals

Perk Optimization

"What perks should I create for my coffee shop brand?"

Tools used: suggest_perks, perk_intelligence, brand_audience

Brand Comparison

"How does Brand A compare to Brand B?"

Tools used: compare_brands, brand_analytics, brand_health

Program Health

"How healthy is my reward program?"

Tools used: brand_health, brand_analytics, event_performance, perk_analytics

Cross-Brand Strategy

"How are users flowing between brands in retail?"

Tools used: network_flows, network_trending, network_analytics

CLI Usage

# Simple query
rsnc converse "What are the best coffee deals right now?"

# With session context
rsnc converse "How healthy is my program?" --context '{"brandId":"0xABC"}'

Error Responses

Status	Code	Description
401	auth_required	Missing or invalid HMAC credentials
403	forbidden	API key does not have pro/enterprise tier
400	validation	Empty or invalid query
500	internal	Pipeline execution failure

Rate Limits

Converse requests count against your authenticated rate limit (default: 20 requests/minute per key). Each converse request may internally call multiple tools but counts as a single request.