useSendMessage

Send messages back to the ChatGPT conversation from your widget. This hook allows your widget to communicate with the user by sending text, rich content, or structured data back to the chat.

Usage

import { useSendMessage } from '@chatgpt-apps/sdk';

function MyWidget() {
  const sendMessage = useSendMessage();

  const handleSubmit = async () => {
    await sendMessage({
      type: 'text',
      content: 'Action completed successfully!',
    });
  };

  return <button onClick={handleSubmit}>Complete Action</button>;
}

Parameters

The hook itself accepts no parameters. The returned function accepts:

Parameter	Type	Description
`message`	`MessagePayload`	The message to send to the conversation

MessagePayload Types

type MessagePayload =
  | TextMessage
  | RichTextMessage
  | StructuredDataMessage;

interface TextMessage {
  type: 'text';
  content: string;
}

interface RichTextMessage {
  type: 'rich_text';
  content: string;
  format: 'markdown' | 'html';
}

interface StructuredDataMessage {
  type: 'data';
  content: unknown;
}

Return Type

Returns a function with the following signature:

type SendMessageFunction = (
  message: MessagePayload
) => Promise<void>;

Example

Text Message

import { useSendMessage } from '@chatgpt-apps/sdk';

function SimpleWidget() {
  const sendMessage = useSendMessage();

  const notifyUser = (status: string) => {
    sendMessage({
      type: 'text',
      content: `Operation status: ${status}`,
    });
  };

  return (
    <div>
      <button onClick={() => notifyUser('success')}>
        Mark as Complete
      </button>
      <button onClick={() => notifyUser('pending')}>
        Mark as Pending
      </button>
    </div>
  );
}

Rich Text (Markdown)

import { useSendMessage } from '@chatgpt-apps/sdk';

function ReportWidget() {
  const sendMessage = useSendMessage();

  const sendReport = () => {
    const markdown = `
## Analysis Complete

**Summary:** All checks passed successfully.

| Metric | Value |
|--------|-------|
| Items processed | 42 |
| Errors | 0 |
| Duration | 1.2s |

[View Details](https://example.com/details)
    `.trim();

    sendMessage({
      type: 'rich_text',
      content: markdown,
      format: 'markdown',
    });
  };

  return <button onClick={sendReport}>Send Report</button>;
}

Structured Data

import { useSendMessage } from '@chatgpt-apps/sdk';

function DataWidget() {
  const sendMessage = useSendMessage();

  const shareResults = (results: AnalysisResult[]) => {
    sendMessage({
      type: 'data',
      content: {
        timestamp: new Date().toISOString(),
        results,
        summary: {
          total: results.length,
          passed: results.filter(r => r.passed).length,
          failed: results.filter(r => !r.passed).length,
        },
      },
    });
  };

  return (
    <AnalysisComponent onComplete={shareResults} />
  );
}

With Confirmation

import { useSendMessage } from '@chatgpt-apps/sdk';

function ConfirmWidget() {
  const sendMessage = useSendMessage();
  const [sending, setSending] = useState(false);

  const confirmAction = async () => {
    setSending(true);
    try {
      await sendMessage({
        type: 'text',
        content: 'Confirmed: The action has been executed.',
      });
    } catch (error) {
      console.error('Failed to send message:', error);
    } finally {
      setSending(false);
    }
  };

  return (
    <button onClick={confirmAction} disabled={sending}>
      {sending ? 'Sending...' : 'Confirm'}
    </button>
  );
}

Interactive Response

import { useSendMessage } from '@chatgpt-apps/sdk';

function FeedbackWidget() {
  const sendMessage = useSendMessage();

  const sendFeedback = (rating: number, comment: string) => {
    const messages = [
      'Poor',
      'Fair',
      'Good',
      'Very Good',
      'Excellent',
    ];

    sendMessage({
      type: 'rich_text',
      content: `**Feedback Received**\n\nRating: ${'⭐'.repeat(rating)}\nComment: ${comment || 'No comment provided'}`,
      format: 'markdown',
    });
  };

  return (
    <div>
      {[1, 2, 3, 4, 5].map((rating) => (
        <button
          key={rating}
          onClick={() => sendFeedback(rating, 'Great widget!')}
        >
          {rating} Stars
        </button>
      ))}
    </div>
  );
}

Notes

Messages appear in the ChatGPT conversation thread
Use rich_text with markdown format for formatted content
Use data type for sharing structured results that can be processed
The function returns a Promise; await it to handle success/error states
Avoid sending sensitive information as messages are visible in the conversation

useSendMessage

On this page