Description

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!"
    }
  },
  "channelpriorityorder": ["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 | INVALIDARGUMENT | Malformed request body | Check appid, 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 | NOTFOUND | Resource not found | Verify appid 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.