n8n-nodes-sinch

Community node for n8n to send and manage omnichannel messages via Sinch Conversations API.

Installation

Using n8n Community Nodes

1. Open your n8n instance
2. Go to Settings > Community Nodes
3. Enter @sinch/n8n-nodes-sinch
4. Click Install

Manual Installation

cd ~/.n8n
npm install @sinch/n8n-nodes-sinch

Compatibility

• n8n: 1.0.0 or later
• Node.js: 20.19 or later (up to 24.x)

Features

• Send SMS messages via Sinch Conversations API (routed through Econexus)
• Send WhatsApp Template Message with approved templates from Sinch Provisioning API
• Get Many messages with filtering and pagination
• Message Delivered trigger via Econexus ISS webhook subscriptions
• OAuth2.0 authentication with automatic token management
• Multi-region support (US, EU, BR)
• Phone number normalization to E.164 format
• Robust error handling and validation

Node Configuration

Basic Information

• Display Name: Sinch
• Name: sinch
• Group: output
• Inputs: main
• Outputs: main

Operations

Send Message

Send SMS messages via Sinch Conversations API.

Fields:

• To (required) - Recipient phone number in E.164 format (e.g., +15551234567)
• Country (optional) - Country for parsing local phone numbers without international prefix
• Message (required, up to 1600 characters) - Message text to send
• SMS Sender (optional) - Sender address (alphanumeric or phone number)
• Callback URL (optional) - Webhook URL for delivery status updates
• Metadata (optional) - Custom metadata to associate with the message (up to 1024 characters)

Send WhatsApp Template Message

Send an approved WhatsApp template via Sinch Conversation API. Templates are loaded from the Sinch Provisioning API; body placeholders ({{1}}, {{2}}, …) are shown as input fields after you select a template.

Fields:

• To (required) - Recipient WhatsApp number in E.164 format (e.g., +14155552671)
• WhatsApp Template Name or ID (required) - Approved template from your Sinch project (value format: templateName,languageCode)
• Template Body Variable Count Name or ID - Auto-loaded when the template changes; lists how many body variables the template expects
• Variable {{1}} … Variable {{20}} - Shown based on the template variable count (up to 20 placeholders)

API endpoints used:

• List templates: GET https://provisioning.api.sinch.com/v1/projects/{projectId}/whatsapp/templates?filterStates=APPROVED
• Template detail: GET .../whatsapp/templates/{name}/languages/{language}
• Send: POST https://{au|eu}.app.api.sinch.com/v1/econexus/sinch-build/v1/projects/{projectId}/messages:send

Get Many Messages

Retrieve and filter messages from conversations.

Controls:

• Return All - Whether to return all results or only up to a given limit
• Limit - Max number of results to return (default: 50)

Filters:

• Contact ID - Filter by contact ID
• Conversation ID - Filter by conversation ID
• Start Time - Filter messages after this timestamp
• End Time - Filter messages before this timestamp
• Page Size - Number of messages per page (max 1000, default: 10)
• Channel - Filter by channel (SMS, WhatsApp, RCS)

Sinch Trigger

Webhook trigger for message delivery events.

Events:

• Message Delivered - Fires when a MESSAGE_DELIVERY webhook is received with status DELIVERED

When a workflow is activated, the trigger registers an ISS subscription with Econexus. When the workflow is deactivated, the subscription is removed automatically.

Output fields:

• messageId, conversationId, deliveryStatus, channel, contactIdentity, contactId, appId, projectId, eventTime, acceptedTime, metadata

Credentials

Sinch Conversations API

Required Fields:

• Key ID (Client ID) - Your Sinch API Key ID from the dashboard
• Key Secret (Client Secret) - Your Sinch API Key Secret from the dashboard
• Region - Region where your Conversation API app was created (US, EU, or BR)
• Project ID - Your Sinch Project ID from the dashboard
• App ID - Your Sinch Conversation API App ID

Authentication: OAuth2.0 (automatic token management)

Getting Your Credentials

1. Create a Sinch account at https://dashboard.sinch.com
2. Create a project
3. Generate API keys in Settings > Access Keys
4. Create a Conversation API app
5. Note your Project ID and App ID

API Endpoints

All Conversation API requests are routed through the Econexus Sinch Build proxy:

• US / BR: https://au.app.api.sinch.com/v1/econexus/sinch-build
• EU: https://eu.app.api.sinch.com/v1/econexus/sinch-build

ISS webhook subscriptions:

• US / BR: https://au.app.api.sinch.com/v1/econexus/iss/subscriptions
• EU: https://eu.app.api.sinch.com/v1/econexus/iss/subscriptions

Send Message

Endpoint: POST /v1/projects/{projectId}/messages:send

Request Body:

{
  "app_id": "your-app-id",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "SMS",
          "identity": "+15551234567"
        }
      ]
    }
  },
  "message": {
    "text_message": {
      "text": "Hello from n8n!"
    }
  },
  "channel_priority_order": ["SMS"],
  "callback_url": "https://webhook.site/...",
  "message_metadata": "custom-id-123"
}

Response:

{
  "message_id": "msg-123",
  "accepted_time": "2024-01-01T00:00:00Z"
}

Get Many Messages

Endpoint: GET /v1/projects/{projectId}/messages

Query Parameters:

• app_id (required)
• contact_id (optional)
• conversation_id (optional)
• start_time (optional, ISO 8601)
• end_time (optional, ISO 8601)
• page_size (optional, max 1000)
• channel (optional)

Authentication

OAuth2.0 authentication is automatically handled:

1. Tokens are fetched from https://{region}.auth.sinch.com/oauth2/token
2. Tokens are cached for 55 minutes (5-minute buffer before expiry)
3. Tokens are automatically refreshed when expired
4. Bearer tokens are used in Authorization headers
5. Econexus proxy headers (X-AUTH-SOURCE, X-SINCH-APP-ID, X-SINCH-PROJECT-ID, X-CLIENT-SOURCE) are sent on all Econexus requests

Phone Number Format

E.164 Format

Phone numbers must be in E.164 format:

• International format: +15551234567
• Local format: 5551234567 (requires Country field)

Supported Formats

• +15551234567 (international format)
• 15551234567 with Country = US -> +15551234567
• 0437536808 with Country = AU -> +61437536808
• 00 prefix is automatically converted to +

Example Workflow

{
  "name": "Send SMS via Sinch",
  "nodes": [
    {
      "parameters": {
        "resource": "message",
        "operation": "send",
        "to": "+15551234567",
        "message": "Hello from n8n!",
        "additionalFields": {
          "callbackUrl": "https://webhook.site/unique-id"
        }
      },
      "type": "@sinch/n8n-nodes-sinch.sinch",
      "typeVersion": 1,
      "position": [250, 300],
      "id": "abc123",
      "name": "Sinch",
      "credentials": {
        "sinchApi": {
          "id": "1",
          "name": "Sinch Conversations API"
        }
      }
    }
  ],
  "connections": {}
}

Troubleshooting

Common Issues

• 401 Unauthorized: Check your Key ID and Key Secret
• 403 Forbidden: Verify your Project ID matches the credentials
• 404 Not Found: Verify your App ID exists and region matches
• 429 Rate Limit: Implement backoff or check Sinch API rate limits
• Invalid phone number: Ensure phone number is in E.164 format or provide Country field

Error Codes

| HTTP Code | Sinch Status | Description | Resolution | |-----------|--------------|-------------|------------| | 400 | INVALID_ARGUMENT | Malformed request body | Check app_id, project_id, message format | | 401 | UNAUTHENTICATED | Invalid credentials | Verify Key ID and Secret | | 403 | UNAUTHORIZED | No access to resource | Check project_id matches credentials | | 404 | NOT_FOUND | Resource not found | Verify app_id exists, region matches | | 429 | RESOURCE_EXHAUSTED | Rate limit exceeded | Implement backoff, check rate limits | | 500 | INTERNAL | Server error | Retry with exponential backoff |

Resources

• Sinch Conversations API Docs: https://developers.sinch.com/docs/conversation/
• Send Message Endpoint: https://developers.sinch.com/docs/conversation/api-reference/conversation/messages/messages_sendmessage
• List Messages Endpoint: https://developers.sinch.com/docs/conversation/api-reference/conversation/messages/messages_listmessages
• OAuth2.0 Guide: https://developers.sinch.com/docs/conversation/api-reference/conversation/#oauth20-authentication
• Sinch Dashboard: https://dashboard.sinch.com

License

MIT License

Contributing

Contributions, issues, and feature requests are welcome. Please open an issue on the GitHub repository before submitting a pull request.