Sinch

Sinch Connection

Put Sinch to Work with @Human Automations and @Human Agents

The Sinch Connection documents all Triggers, Actions and Query Operations available for creating automations via the Sinch API.

What can you do with the Sinch Connection?

• Connect to the Sinch API in a few clicks

• Use the related Sinch Operations (see below) in @Human Automations or @Human Agents

Related Operations

Trigger Operations

SMS Delivered

Triggers on: sms/delivered

Triggered when an SMS message is successfully delivered to the recipient.

Voice Call Answered

Triggers on: voice/answered

Triggered when a voice call is answered by the recipient.

Action Operations

Action: Buy Phone Number

Action: Send a Fax

Action: Send a Message

Query Operations

Example link

Related Automations

Example link

Obtaining Access Credentials

To obtain a Personal Access Token (PAT) for Sinch (system-to-system access), follow these steps:

Prerequisites

• A Sinch account with admin/subscription access to generate tokens.

• Ensure you have API access enabled for your Sinch project.

Steps to Generate a PAT in Sinch

1. Log in to the Sinch Customer Dashboard.

2. Navigate to: API → Authentication (or Settings → API Keys, depending on UI updates).

3. Click Create New Token (or Generate PAT).

4. Provide:

   • Token Name (descriptive, e.g., System-Integration-PAT).

   • Expiration (set as needed; no expiry = permanent).

   • Permissions/Scopes (select required APIs, e.g., SMS, Voice, Verification).

5. Click Generate.

6. Copy the token immediately—it won’t be shown again.

Configuring Webhooks

1. Log in to the Sinch Customer Dashboard.

2. Navigate to the specific service (e.g., Conversation API, SMS, or Voice) in the left-hand navigation menu.

3. Click on Apps and select the specific app you want to configure.

4. Locate the Webhooks or Callbacks section within the app details page.

5. Click Create Webhook or Add Callback URL.

6. Provide the Target URL where you want to receive event notifications.

7. Select the Triggers or Events you want to subscribe to.

8. Click Create or Save to activate the webhook configuration.

Code (Apache v2.0): Service Connectivity and Metadata

{
  "handle": "sinch",
  "status": "active",
  "meta": {
    "short": "Sinch",
    "description": "A connector for integrating with Sinch's communication APIs, including SMS, voice, and verification services.",
    "icon": "sinch",
    "tags": ["communication", "sms", "voice", "verification"]
  },
  "service": {
    "baseURL": {
      "value": "https://{{region}}.api.sinch.com"
    },
    "protocol": "https",
    "contentType": "application/json",
    "headers": {
      "Content-Type": {
        "value": "application/json"
      }
    },
    "auth": {
      "method": "basic",
      "params": {
        "basic": {
          "username": {
            "value": "{{username}}",
            "placeholders": [
              {
                "name": "username",
                "type": "String",
                "description": "Sinch API username",
                "required": true
              }
            ]
          },
          "password": {
            "value": "{{password}}",
            "placeholders": [
              {
                "name": "password",
                "type": "String",
                "description": "Sinch API password",
                "required": true
              }
            ]
          }
        }
      }
    }
  }
}

Code (Apache v2.0): List of External Resources and Internal Mapping

[
  {
    "handle": "sms",
    "meta": {
      "short": "SMS",
      "description": "Send and receive SMS messages"
    },
    "endpoint": {
      "value": "/v1/sms"
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": ["id"],
        "meta": {
          "description": "Unique identifier for the SMS message"
        }
      },
      {
        "name": "body",
        "type": "String",
        "selector": ["body"],
        "meta": {
          "description": "Content of the SMS message"
        }
      },
      {
        "name": "to",
        "type": "String",
        "selector": ["to", "number"],
        "meta": {
          "description": "Recipient phone number"
        }
      },
      {
        "name": "from",
        "type": "String",
        "selector": ["from", "number"],
        "meta": {
          "description": "Sender phone number"
        }
      },
      {
        "name": "status",
        "type": "String",
        "selector": ["status", "code"],
        "meta": {
          "description": "Delivery status of the SMS"
        }
      }
    ],
    "operations": {
      "list": {
        "method": "GET",
        "path": {
          "value": "/"
        },
        "queryParams": {
          "limit": {
            "value": "{{limit}}",
            "placeholders": [
              {
                "name": "limit",
                "type": "Integer",
                "description": "Number of SMS messages to retrieve",
                "required": false,
                "default": "10"
              }
            ]
          }
        }
      },
      "read": {
        "method": "GET",
        "path": {
          "value": "/{{id}}",
          "placeholders": [
            {
              "name": "id",
              "type": "String",
              "description": "ID of the SMS message",
              "required": true
            }
          ]
        }
      },
      "create": {
        "method": "POST",
        "path": {
          "value": "/"
        },
        "bodyTemplate": {
          "value": "{\"to\": [{\"number\": \"{{to}}\"}], \"body\": \"{{body}}\", \"from\": \"{{from}}\"}",
          "placeholders": [
            {
              "name": "to",
              "type": "String",
              "description": "Recipient phone number",
              "required": true
            },
            {
              "name": "body",
              "type": "String",
              "description": "Content of the SMS message",
              "required": true
            },
            {
              "name": "from",
              "type": "String",
              "description": "Sender phone number",
              "required": true
            }
          ]
        }
      }
    },
    "webhooks": [
      {
        "event": "delivered",
        "path": "/webhooks/sinch/sms/delivered",
        "payload": [
          {
            "name": "messageId",
            "type": "String",
            "selector": ["message_id"],
            "meta": {
              "description": "ID of the delivered SMS message"
            }
          },
          {
            "name": "status",
            "type": "String",
            "selector": ["status", "code"],
            "meta": {
              "description": "Delivery status code"
            }
          }
        ]
      }
    ]
  },
  {
    "handle": "voice",
    "meta": {
      "short": "Voice",
      "description": "Manage voice calls"
    },
    "endpoint": {
      "value": "/v1/calls"
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": ["id"],
        "meta": {
          "description": "Unique identifier for the call"
        }
      },
      {
        "name": "status",
        "type": "String",
        "selector": ["status"],
        "meta": {
          "description": "Current status of the call"
        }
      },
      {
        "name": "direction",
        "type": "String",
        "selector": ["direction"],
        "meta": {
          "description": "Direction of the call (inbound/outbound)"
        }
      },
      {
        "name": "from",
        "type": "String",
        "selector": ["from", "number"],
        "meta": {
          "description": "Caller phone number"
        }
      },
      {
        "name": "to",
        "type": "String",
        "selector": ["to", "number"],
        "meta": {
          "description": "Callee phone number"
        }
      }
    ],
    "operations": {
      "list": {
        "method": "GET",
        "path": {
          "value": "/"
        }
      },
      "read": {
        "method": "GET",
        "path": {
          "value": "/{{id}}",
          "placeholders": [
            {
              "name": "id",
              "type": "String",
              "description": "ID of the call",
              "required": true
            }
          ]
        }
      },
      "create": {
        "method": "POST",
        "path": {
          "value": "/"
        },
        "bodyTemplate": {
          "value": "{\"destination\": {\"number\": \"{{to}}\"}, \"cli\": \"{{from}}\"}",
          "placeholders": [
            {
              "name": "to",
              "type": "String",
              "description": "Callee phone number",
              "required": true
            },
            {
              "name": "from",
              "type": "String",
              "description": "Caller phone number",
              "required": true
            }
          ]
        }
      }
    },
    "webhooks": [
      {
        "event": "answered",
        "path": "/webhooks/sinch/voice/answered",
        "payload": [
          {
            "name": "callId",
            "type": "String",
            "selector": ["call_id"],
            "meta": {
              "description": "ID of the answered call"
            }
          },
          {
            "name": "status",
            "type": "String",
            "selector": ["status"],
            "meta": {
              "description": "Call status"
            }
          }
        ]
      }
    ]
  },
  {
    "handle": "verify",
    "meta": {
      "short": "Verify",
      "description": "Phone number verification service"
    },
    "endpoint": {
      "value": "/v1/verifications"
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": ["id"],
        "meta": {
          "description": "Unique identifier for the verification"
        }
      },
      {
        "name": "number",
        "type": "String",
        "selector": ["number"],
        "meta": {
          "description": "Phone number being verified"
        }
      },
      {
        "name": "status",
        "type": "String",
        "selector": ["status"],
        "meta": {
          "description": "Verification status"
        }
      },
      {
        "name": "method",
        "type": "String",
        "selector": ["method"],
        "meta": {
          "description": "Verification method (sms/flashcall)"
        }
      }
    ],
    "operations": {
      "create": {
        "method": "POST",
        "path": {
          "value": "/"
        },
        "bodyTemplate": {
          "value": "{\"identity\": {\"type\": \"number\", \"endpoint\": \"{{number}}\"}, \"method\": \"{{method}}\"}",
          "placeholders": [
            {
              "name": "number",
              "type": "String",
              "description": "Phone number to verify",
              "required": true
            },
            {
              "name": "method",
              "type": "String",
              "description": "Verification method",
              "required": false,
              "default": "sms",
              "options": ["sms", "flashcall"]
            }
          ]
        }
      },
      "read": {
        "method": "GET",
        "path": {
          "value": "/{{id}}",
          "placeholders": [
            {
              "name": "id",
              "type": "String",
              "description": "Verification ID",
              "required": true
            }
          ]
        }
      }
    }
  },
  {
    "handle": "conversation",
    "meta": {
      "short": "Conversation",
      "description": "Omni-channel messaging via the Conversation API"
    },
    "endpoint": {
      "value": "/v1/projects/{{project_id}}/messages"
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": ["id"],
        "meta": {
          "description": "Unique identifier for the message"
        }
      },
      {
        "name": "project_id",
        "type": "String",
        "selector": ["project_id"],
        "meta": {
          "description": "Project ID for the conversation"
        }
      },
      {
        "name": "app_id",
        "type": "String",
        "selector": ["app_id"],
        "meta": {
          "description": "App ID for the conversation"
        }
      },
      {
        "name": "contact_id",
        "type": "String",
        "selector": ["contact_id"],
        "meta": {
          "description": "ID of the contact"
        }
      },
      {
        "name": "direction",
        "type": "String",
        "selector": ["direction"],
        "meta": {
          "description": "Direction of the message (TO_CONTACT or FROM_CONTACT)"
        }
      },
      {
        "name": "text",
        "type": "String",
        "selector": ["message", "text_message", "text"],
        "meta": {
          "description": "Text content of the message"
        }
      }
    ],
    "operations": {
      "read": {
        "method": "GET",
        "path": {
          "value": "/{{id}}",
          "placeholders": [
            {
              "name": "id",
              "type": "String",
              "description": "ID of the message",
              "required": true
            }
          ]
        }
      },
      "list": {
        "method": "GET",
        "path": {
          "value": "/"
        }
      },
      "send": {
        "method": "POST",
        "path": {
          "value": ":send"
        },
        "bodyTemplate": {
          "value": "{\"app_id\": \"{{app_id}}\", \"recipient\": {\"contact_id\": \"{{contact_id}}\"}, \"message\": {\"text_message\": {\"text\": \"{{text}}\"}}, \"channel_priority_order\": [\"{{channel}}\"]}",
          "placeholders": [
            {
              "name": "app_id",
              "type": "String",
              "description": "The ID of the conversaton app",
              "required": true
            },
            {
              "name": "contact_id",
              "type": "String",
              "description": "ID of the recipient contact.",
              "required": true
            },
            {
              "name": "text",
              "type": "String",
              "description": "Text content to send",
              "required": true
            },
            {
              "name": "channel",
              "type": "String",
              "description": "Channel priority order (e.g. SMS, WHATSAPP)",
              "required": true
            }
          ]
        }
      }
    }
  },
  {
    "handle": "contact",
    "meta": {
      "short": "Contact",
      "description": "Manage contacts for the Conversation API"
    },
    "endpoint": {
      "value": "/v1/projects/{{project_id}}/contacts"
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": ["id"],
        "meta": {
          "description": "Unique identifier for the contact"
        }
      },
      {
        "name": "display_name",
        "type": "String",
        "selector": ["display_name"],
        "meta": {
          "description": "Display name of the contact"
        }
      },
      {
        "name": "email",
        "type": "String",
        "selector": ["email"],
        "meta": {
          "description": "Email address of the contact"
        }
      },
      {
        "name": "external_id",
        "type": "String",
        "selector": ["external_id"],
        "meta": {
          "description": "External reference ID for the contact"
        }
      },
      {
        "name": "language",
        "type": "String",
        "selector": ["language"],
        "meta": {
          "description": "Language preference of the contact"
        }
      }
    ],
    "operations": {
      "read": {
        "method": "GET",
        "path": {
          "value": "/{{id}}",
          "placeholders": [
            {
              "name": "id",
              "type": "String",
              "description": "ID of the contact",
              "required": true
            }
          ]
        }
      },
      "list": {
        "method": "GET",
        "path": {
          "value": "/"
        }
      },
      "create": {
        "method": "POST",
        "path": {
          "value": "/"
        },
        "bodyTemplate": {
          "value": "{\"channel_identities\": [{\"channel\": \"{{channel}}\", \"identity\": \"{{identity}}\"}], \"display_name\": \"{{display_name}}\", \"language\": \"{{language}}\"}",
          "placeholders": [
            {
              "name": "channel",
              "type": "String",
              "description": "Communication channel (e.g., SMS, WHATSAPP)",
              "required": true
            },
            {
              "name": "identity",
              "type": "String",
              "description": "Channel identity alias (e.g., phone number)",
              "required": true
            },
            {
              "name": "display_name",
              "type": "String",
              "description": "Display name for the contact",
              "required": false
            },
            {
              "name": "language",
              "type": "String",
              "description": "Language preference of the contact",
              "required": false
            }
          ]
        }
      }
    }
  }
]