Messaging API

Send encrypted messages with document attachments and signature requests to verified UIP users.

Overview

The Messaging API enables secure, encrypted communication between your application and UIP users. Send text messages, documents for signing, legal contracts, and other important communications with configurable notification priorities.

Message Types

  • " Text Messages - Secure notifications, alerts, communications
  • " Document Messages - Contracts, legal docs, files requiring signature

Pricing

  • =� $0.03 per text message
  • =� $0.10 per message with attachment

Notification Severity Levels

Control how urgently users are notified about your messages with four severity levels:

Low

No push notification - background delivery only. User sees message when they open the UIP app.

Medium

Standard push notification with default sound and vibration.

High

Priority notification with enhanced sound and persistent alert until acknowledged.

Extreme

Emergency-level notification with maximum alert intensity. Reserved for government/emergency use.

Note: Extreme severity is restricted to verified government and emergency service accounts.

Endpoint

POST https://msg.api.uip.id/v1

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Parameters

ParameterTypeRequiredDescription
recipient_uip_idstringYesUIP ID of the message recipient
webhook_urlstringYesURL to receive message delivery and response events
subjectstringYesMessage subject/title
messagestringYesMessage content/body
severitystringNoNotification priority: low, medium, high, extreme (default: medium)
attachmentobjectNoDocument attachment (up to 20MB)
requires_signaturebooleanNoWhether the message/document requires a signature (default: false)

Request Examples

Simple Text Message

{
  "recipient_uip_id": "MyBank",
  "recipient_uip_id": "uip_user_1234567890",
  "webhook_url": "https://mybank.com/webhooks/uip/msg",
  "subject": "Account Alert",
  "message": "Your account has been successfully verified. Welcome to MyBank!",
  "severity": "medium"
}
=� Cost: $0.03

Document Message with Signature Required

{
  "recipient_uip_id": "LegalFirm LLC",
  "recipient_uip_id": "uip_user_1234567890",
  "webhook_url": "https://legalfirm.com/webhooks/uip/contracts",
  "subject": "Employment Contract - Please Review and Sign",
  "message": "Please review the attached employment contract and provide your signature if you agree to the terms.",
  "severity": "high",
  "attachment": {
    "filename": "employment_contract_2024.pdf",
    "content_type": "application/pdf",
    "data": "base64_encoded_pdf_data_here...",
    "size": 1048576
  },
  "requires_signature": true
}
=� Cost: $0.10 (includes document attachment)

Emergency Notification

{
  "recipient_uip_id": "Emergency Services",
  "recipient_uip_id": "uip_user_1234567890",
  "webhook_url": "https://emergency.gov/webhooks/uip/alerts",
  "subject": "EMERGENCY ALERT - Severe Weather Warning",
  "message": "Severe weather warning in your area. Seek shelter immediately. This is not a drill.",
  "severity": "extreme"
}
=� Cost: $0.03 | � Restricted: Government/Emergency accounts only

Attachment Format

When including document attachments, use this format within the attachment object:

"attachment": {
  "filename": "contract.pdf",
  "content_type": "application/pdf",
  "data": "base64_encoded_file_data",
  "size": 1048576
}

Supported File Types

  • " PDF documents (application/pdf)
  • " Word documents (application/vnd.openxmlformats-officedocument.wordprocessingml.document)
  • " Images (image/jpeg, image/png)
  • " Text files (text/plain)
  • " CSV files (text/csv)

Limits

  • " Maximum file size: 20MB
  • " One attachment per message
  • " Base64 encoding required
  • " File size must match actual data

Response Format

{
  "message_id": "msg_1234567890abcdef",
  "status": "sent",
  "recipient_uip_id": "uip_user_1234567890",
  "estimated_delivery": "2024-01-15T10:30:00Z",
  "requires_signature": false,
  "cost": 0.03
}

Response Fields

FieldTypeDescription
message_idstringUnique identifier for this message
statusstringMessage status: sent, delivered, read, failed
recipient_uip_idstringConfirmed recipient UIP ID
estimated_deliverystringEstimated delivery timestamp
requires_signaturebooleanWhether message requires signature
costnumberCost of sending this message in USD

Webhook Events

You'll receive webhook notifications for message delivery status, read receipts, and signature completions.

Message Delivered

{
  "event": "message_delivered",
  "message_id": "msg_1234567890abcdef",
  "recipient_uip_id": "uip_user_1234567890",
  "delivered_at": "2024-01-15T10:30:00Z",
  "status": "delivered"
}

Message Read

{
  "event": "message_read",
  "message_id": "msg_1234567890abcdef",
  "recipient_uip_id": "uip_user_1234567890",
  "read_at": "2024-01-15T10:35:00Z",
  "status": "read"
}

Document Signed

{
  "event": "document_signed",
  "message_id": "msg_1234567890abcdef",
  "recipient_uip_id": "uip_user_1234567890",
  "signed_at": "2024-01-15T10:45:00Z",
  "signature_data": {
    "document_hash": "sha256:a1b2c3d4e5f6...",
    "signature": "uip_sig_abc123def456...",
    "signer_info": {
      "full_name": "Alice Johnson",
      "verified": true,
      "verification_level": "government_id"
    }
  },
  "status": "signed"
}

Complete Implementation

// JavaScript implementation
async function sendUIPMessage(recipientUipId, subject, message, options = {}) {
  try {
    const payload = {
      recipient_uip_id: recipientUipId,
      webhook_url: 'https://myapp.com/webhooks/uip/msg',
      subject: subject,
      message: message,
      severity: options.severity || 'medium'
    };

    // Add attachment if provided
    if (options.attachment) {
      payload.attachment = options.attachment;
    }

    // Add signature requirement if specified
    if (options.requiresSignature) {
      payload.requires_signature = true;
    }

    const response = await fetch('https://msg.api.uip.id/v1', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + YOUR_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log(`Message sent successfully. ID: ${data.message_id}, Cost: $${data.cost}`);
    
    return data;
  } catch (error) {
    console.error('UIP message sending failed:', error);
    throw error;
  }
}

// Helper function to encode file as base64
function encodeFileAsBase64(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result.split(',')[1]); // Remove data:mime;base64, prefix
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
}

// Usage examples

// Simple text message
sendUIPMessage(
  'uip_user_1234567890',
  'Welcome!',
  'Thank you for joining our platform.',
  { severity: 'medium' }
);

// Document with signature required
const contractFile = document.getElementById('contract-file').files[0];
const base64Data = await encodeFileAsBase64(contractFile);

sendUIPMessage(
  'uip_user_1234567890',
  'Employment Contract - Please Sign',
  'Please review and sign the attached employment contract.',
  {
    severity: 'high',
    requiresSignature: true,
    attachment: {
      filename: contractFile.name,
      content_type: contractFile.type,
      data: base64Data,
      size: contractFile.size
    }
  }
);

Next Steps

Ready to implement UIP messaging in your application?