Send encrypted messages with document attachments and signature requests to verified UIP users.
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.
Control how urgently users are notified about your messages with four severity levels:
No push notification - background delivery only. User sees message when they open the UIP app.
Standard push notification with default sound and vibration.
Priority notification with enhanced sound and persistent alert until acknowledged.
Emergency-level notification with maximum alert intensity. Reserved for government/emergency use.
Note: Extreme severity is restricted to verified government and emergency service accounts.
https://msg.api.uip.id/v1
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Parameter | Type | Required | Description |
---|---|---|---|
recipient_uip_id | string | Yes | UIP ID of the message recipient |
webhook_url | string | Yes | URL to receive message delivery and response events |
subject | string | Yes | Message subject/title |
message | string | Yes | Message content/body |
severity | string | No | Notification priority: low, medium, high, extreme (default: medium) |
attachment | object | No | Document attachment (up to 20MB) |
requires_signature | boolean | No | Whether the message/document requires a signature (default: false) |
{
"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"
}
{
"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
}
{
"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"
}
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
}
{
"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
}
Field | Type | Description |
---|---|---|
message_id | string | Unique identifier for this message |
status | string | Message status: sent, delivered, read, failed |
recipient_uip_id | string | Confirmed recipient UIP ID |
estimated_delivery | string | Estimated delivery timestamp |
requires_signature | boolean | Whether message requires signature |
cost | number | Cost of sending this message in USD |
You'll receive webhook notifications for message delivery status, read receipts, and signature completions.
{
"event": "message_delivered",
"message_id": "msg_1234567890abcdef",
"recipient_uip_id": "uip_user_1234567890",
"delivered_at": "2024-01-15T10:30:00Z",
"status": "delivered"
}
{
"event": "message_read",
"message_id": "msg_1234567890abcdef",
"recipient_uip_id": "uip_user_1234567890",
"read_at": "2024-01-15T10:35:00Z",
"status": "read"
}
{
"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"
}
// 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
}
}
);